List of commands and features of FreeCOM:

- ALIAS - Display or change an alias
- BEEP - Issue a Beep
- BREAK - Display or Set Extended Break Checking
- CALL - Call a Nested Batchfile or Program
- CANCEL - Terminate all scripts
- CD - Change current directory of a drive
- CDD - Changes the current working directory
- CHDIR - Change current directory of a drive
- CLS - Clear screen
- COPY - Copy one or more files to another location
- CTTY - Change TTY (console)
- DATE - Display or set current date
- DEL - Delete files
- DIR - Displays the contents of the directory
- DIRS - Display the directory stack
- ECHO - Displays a string onto screen
- ENVIRONMENT_KEEP_FREE - keep free space in environment segment
- ERASE - Delete files
- EXIT - Terminate shell
- FEATURE_ALIASES - Command aliases
- FEATURE_AUTO_REDIRECT_TO_CON - Autoswitch CON: to monitor
- FEATURE_BATCH - Batch script processing
- FEATURE_BOOT_KEYS - check for F5/F8 keys on startup if /P is present
- FEATURE_CALL_LOGGING - Startup logging
- FEATURE_DIRSTACK - Directory stack
- FEATURE_ENHANCED_INPUT - Enhanced command line editing
- FEATURE_FILENAME_COMPLETION - Filename completion
- FEATURE_HISTORY - Command line history
- FEATURE_INSTALLABLE_COMMANDS - Installable Commands interface (MUX-AE)
- FEATURE_LAST_DIR - Change back to last directory
- FEATURE_LOAD_MESSAGES - Load messages permanently
- FEATURE_NLS - use DOS NLS
- FOR - Repeat a command
- GOTO - Goto label
- HISTORY - Display command line history
- IF - Conditional execution of a command
- LOADFIX - Load an external program above the first 64KB memory
- LOADHIGH - Load an external program into high memory
- MD - make directory
- MEMORY - Display the internally used memory
- MKDIR - Make directory
- PATH - Display or set the search path
- PAUSE - Pauses batch file execution
- POPD - Change back to the last pushed directory
- PROMPT - Display or set the shell prompt
- PUSHD - Push the current working directory onto the directory stack
- QUIT - Terminate the current script
- RD - Remove directory
- REM - Marks comments or remarks in batchfiles
- REN - Rename files
- RENAME - Rename files
- RMDIR - Remove directory
- SET - Display or set environment variables
- SHIFT - Shift the arguments of a batch script
- TIME - Display or set current time
- TRUENAME - Display the true name of a file
- TYPE - Display the contents of files
- VER - Display the version information about FreeCOM and DOS
- VERIFY - Display or set verify level
- VOL - Display the volume label of a drive
- WHICH - Search and display the executable file of specified commands

## ALIAS - Display or change an alias

Requirements: FEATURE_ALIASES

### Synopsis

1. `ALIAS`
2. `ALIAS` name `'='` [ «string» ]

The first format without any argument displays all defined aliases.

The second format assigns the specified `string` to the alias with the specified `name`. If the `string` is empty, the named alias is removed.

Once an aliase is defined, a command line of the form: `name { argument }`
is replaced by: `<<string>> { argument }`
This mechanism is called alias expansion, because the alias `name` expands to the specified «string». To prevent alias expansion the command must be prefixed by one asterisk, e.g.: `*name arguments`

### Examples

#### Example: 1

``ALIAS` dir=dir /w`
`C> dir`
displays short directory listing from now on.

#### Example: 2

``ALIAS``
displays all currently defined aliases, e.g.:

    DIR=dir /w

in this case.

#### Example: 3

``ALIAS` dir=`
removes the previously defined alias `dir`, thus, `DIR` displays the long output as by default again.

## FEATURE_ALIASES - Command aliases

See also: ALIAS

If defined on compilation of FreeCOM, command aliases are supported.

New aliases are defined using the command:
`ALIAS` name `'='` «string»

Aliases are removed using the command:
`ALIAS` name `'='`

When FreeCOM is interpreting a command line, the command -- the very first word -- is matched against all defined aliases. This word is separated from its arguments by whitespaces and cannot contain any path delimiters, such as backslashes or colons.
If the command matches an alias, the name is substituted by the «string»associated to the aliases, e.g. by defining the alias `ls` by:
``ALIAS` ls=dir /w/o`
let FreeCOM interprete the command line:
`C> ls /a`
exactly as if one had typed in:
`C> dir /w/o /a`

To prevent the alias expansion an asterisk is prefixed before the command, e.g.:
`C> *ls /a`
really tries to execute the command:
`ls /a`
which usually is an external command.

Aliases may be used to hide or re-place internal commands, e.g.:
``ALIAS` dir=xdir`
effectively hides the internal command ``DIR`` and will always execute the -- usually -- external command `XDIR`.

Aliases may be nested, so if both alias definitions mentioned above are in place, the command:
`C> ls /a`
is really executed as:
`xdir /w/o /a`
where the `ls` command is substituted by the command `dir /w/o`, then `dir` is detected as alias, too, and hence replaced by `xdir`.
The same alias is never substituted twice, neither directly nor transitively, so:
``ALIAS` dir=dir /w`
is allowed as well as:
``ALIAS` ls=dir /w/o`
``ALIAS` dir=ls -l`

command | results in
--- | ---
`ls` | `ls -l /w/o`
`dir` | `dir /w/o -l`

As implied above, aliases are expanded when needed and not when they are defined.

Aliases are storred for each instance of FreeCOM individually and are inherited by secondary instances from the parent.

### Options

Compile-time options:

- `ALIAS_DEFAULT_SIZE`: The size reserved for all aliases per FreeCOM instance. Default: 1024

## BEEP - Issue a Beep

Requirements: CMD_BEEP

### Synopsis

`BEEP`

Issues a beep.
At this time FreeCOM supports audible beeps only.

## BREAK - Display or Set Extended Break Checking

Requirements: CMD_BREAK

### Synopsis

`BREAK` [ `ON` | `OFF` ]

Displays or sets the Extended Break status.

By pressing ^Break or ^C (Control-Break or Control-C) an user may signal the currently running program to halt. Most programs will abort to the prompt, but some may decide to just cancel the current action, but remain active.

DOS checks for ^Break/^C (Control-Break or Crontrol-C) each time a program issues a console input/output request. When Extended Break checking is enabled (ON), DOS checks for ^Break each time a program issues a request.

## CALL - Call a Nested Batchfile or Program

See also: LOADFIX, LOADHIGH
Optional requirements: FEATURE_KERNEL_SWAP_SHELL

### Synopsis

1. `CALL` [/Y] program [ «arguments» ]
2. `CALL` [/Y] [ /S | /N ] program [ «arguments» ]

Calls a program or batch script.

If the `program` is a batch script, that means it has the extension `.BAT`, ``CALL`` nests the batch script within the already running one. Without ``CALL`` the invoked batch script would terminate all already running batch scripts.

If present, the arguments are passed unchanged to the invoked program.

### Options

Unless stated otherwise all options of this command do follow the standard rules for options.

- `/S`: If `program` is not a batch script, the external program is executed by swapping FreeCOM out of memory. This process will require more time, especially if FreeCOM is to be reloaded from a floppy, some internal settings are lost, e.g. command line history, but it will free as much memory as possible for the external program.

  This option and, thereby, this function is available only, if FreeCOM had been compiled with some support for swapping.

- `/N`: If `program` is not a batch script, the external program is executed directly, with swapping disabled. `/N` superceeds `/S`.
- `/Y`: Enables tracemode during execution of the command.

Note: In the future to swap FreeCOM out of memory during the execution of an external program will be the default behaviour.

## CANCEL - Terminate all scripts

### Synopsis

`CANCEL` [ n ]
Terminates all currently active batch scripts and, if present, assigns the specified number `n` to the errorlevel.

Note: This command is a hidden internal command.

## CD - Change current directory of a drive

See also: CDD, CHDIR, DIR, DIRS, MD, PUSHD, RD
Requirements: CMD_CHDIR
Optional requirements: FEATURE_LAST_DIR

### Synopsis

1. `CD`
2. `CD` [ drive `':'` ] path
3. `CD` `'-'`

``CD`` is 100% compatible with the ``CHDIR`` command; there is no difference -- beside the spelling -- between them.

The first variant shows the current working directory as absolute path.

The second variant changes the current directory of the given drive. If no drive is specified on command line, the current directory of the currently selected drive (disk) is changed. This command does not change the currently selected drive in opposite to ``CDD``!

The third variant changes back into the last visited directory and drive. The commands ``CD``, ``CHDIR``, ``CDD``, and ``PUSHD`` save the current working directory before performing the specified directory change; the command ``CD` '-'` restores this saved directory. This command is available only, if the feature LAST_DIR has been enabled during the compilation of FreeCOM.

### Options

There are no options for this command.

### Examples

#### Example: 1

``CD` \freedos\help`
Changes the current working directory of the currently selected drive to the path `\FREEDOS\HELP`.

#### Example: 2

``CD` c:\freedos\help`
Changes the current directory of drive `C:`.

#### Example: 3

Assuming the current working directory is `\FREEDOS\HELP` and the currently selected drive is `C:`. ``CD``
Displays `C:\FREEDOS\HELP`

#### Example: 3

The command sequence, provided the first two worked successfully:
``CD` \FREEDOS\HELP`
``CD` ..`
``CD` -`
changes first into the directory `\FREEDOS\HELP`, then into its parent directory, which is `\FREECOM`. And finally ``CD` -` changes back to `\FREEDOS\HELP`, because this was the previous directory before previous ``CD``-like command.

Because ``CD` -` saves the previous directory, too, any subsequent: ``CD` -`
will switch between these two directories; until another directory is changed to.

## CDD - Changes the current working directory

See also: CD, DIR, MD, PUSHD, RD
Requirements: CMD_CDD

### Synopsis

1. `CDD`
2. `CDD` [ drive `':'` ] path
3. `CDD` `'-'`

The behaviour of ``CDD`` is similiar to the ``CD`` command, but it always changes both the currently selected drive and the current directory, thus, it changes the current working directory.

For further details please see the ``CD`` command.

## CHDIR - Change current directory of a drive

This command is 100% compatible to CD, please see there

## CLS - Clear screen

See also: ECHO, TYPE
Requirements: CMD_CLS

### Synopsis

`CLS`
Clears the screen and resets the character colours to white on black.

## COPY - Copy one or more files to another location

See also: DEL, REN
Requirements: CMD_COPY

### Synopsis

1. `COPY` [{ option }] source [{ option }] target [{ option }]

Copies the source file into the target file. See also: \REF{wildcards}

Before parsing its command line `COPY` parses any option specified by the environment variable `COPYCMD`.

### Options

Unless stated otherwise all options of this command do follow the standard rules for options.

- `/A` see below
- `/B`: Specifies the mode, in which the file is copied, `/A` forces ASCII and `/B` forces binary mode.

  These options do alter the mode of the file immediately preceeding them and all following ones, until changed again.

  In binary mode the file is copied and nothing is changed at all.

  In ASCII mode `COPY` takes special care about linefeeds / newline characters and the end-of-line character.

  - On read, the newline characters, which are a sequence of two different bytes in DOS, are transformed into a single character, as known from Unix-style systems. On write, this single character is transformed into the two-byte sequence.
    So, if both files are copied with different modes, newline characters are transformed into either way.
  - If the end-of-file character is found on read, the remaining contents of the file is ignored. On write, such character is appended after the last character has been written.
  By default, files are copied in binary mode, whereas devices, e.g. `CON:`, are copied in ASCII mode, but no end-of-file is appended.

### Arguments

- `source`: The source file.
  If more than one source file is specified, the target must be a directory.
- `target`: The target of the `COPY` process.
  If target is a directory, the destination file is placed into this directory, but with the same filename as the source file.
  If exactly one source is specified, but no target, target defaults to just `.`, which represant the current directory.

## CTTY - Change TTY (console)

Requirements: CMD_CTTY

### Synopsis

`CTTY` device
With this command the console device can be changed. A console device performs all basic input and output operations. This change is more complete than IO-redirections, because latter one might not catch all output, for instance the error messages. See example 3 below.
Because the console is a bidirectional virtual device, meaning it is to perform input and output, the specified `device` must not a unidirectional device, such as `PRN`.

To specify a second argument on the command line of FreeCOM has the same effect.

Attention: This command is to effect the whole system, not only FreeCOM itself; so the effect of `CTTY` does not only depend on the implementation status of FreeCOM, but on the DOS kernel, too.

Also, some programs access the screen or keyboard directly, rather than using the DOS functions; these programs are not effected by `CTTY`.

### Examples

#### Example: 1

``CTTY` aux`
Changes the console to the `AUX:` device, which is usually the first serial communication port `COM1:`. If this line is connected to a terminal or a terminal emulator, the system can be controlled from the terminal by now.

#### Example: 2

``CTTY` nul`
any command sequence
``CTTY` con`
The first command discards any output. If a program attempts any input operation, it gets none. Some programs may not handle such situation correctly.
So, any output, even error messages, are discarded during the command sequence.
The second command changes the console back to the screen/keyboard pair.
To display a string onto screen or read from keybord the usual I/O-redirections may be used, for instance:

- ``ECHO` This line appears on the screen >CON`
- ``PAUSE` >CON`
  This `PAUSE` command will get its input even within the "``CTTY` nul`" environment.

## DATE - Display or set current date

See also: TIME
Requirements: CMD_DATE

### Synopsis

1. `DATE` [ /D ]
2. `DATE` [ /D ] date

The first variant displays the current system date, then enters a loop prompting the user for a new date. The loop terminates, if the user entered a valid new date or just pressed the `ENTER` key.

The second variant does not display the current date and tries to change the date to the specified `date`. On success the command terminates, otherwise enters the loop explained above.

The individual portions of a date may be separated by at least: dots `.`, forward slashes `/` or dashes `-`. Other nationally used characters may be supported, too.
`DATE` will support partial formats:

- A single numnber: specifies the day only.
- Two numbers: specifies the day and the month in the order used by the national date format, which is MM/DD for American and Japanese and DD/MM for European format.
- Three numbers: specifies a full date including day, month and year in the order suitable for the national date format, which is:
  - MM/DD/[CC]YY: for American,
  - DD/MM/[CC]YY: for European and
  - [CC]YY/MM/DD: for Japanese format.
  If the year portion is less than 100, the century is assumed to be 1900, if it is greater or equal than 80; otherwise the century is 2000.

  Note: Some European countries introduced the so-called business date in 1996 or so, which is the same as the Japanese format; it makes sorting of literal dates a lot easier. If FreeCOM will or will not support it, will depend on the NLS used by DOS.

Symbolical names of monthes are not support (yet).

### Options

All options must precced any argument.

`/D` prevents from prompting the user.

1. In variant 1, the date is displayed only.
2. In variant 2, the date is tried to be changed, but the loop is not entered on failure.

### Examples

#### Example: 1

``DATE` /D`
Just display the current system date.

#### Example: 3

``DATE` 2/1/00`
Sets the current date to 1st February of 2000.

## DEL - Delete files

See also: DIR
Requirements: CMD_DELETE

### Synopsis

`DEL` [{ options | pattern }]
Deletes files, if `pattern` matches a directory, all files within this directory are deleted.

When all files are to be deleted, a warning prompt is issued.

### Options

Unless stated otherwise all options of this command do follow the standard rules for options.

- `/P`: Prompts the user before delete a file.
- `/V`: Displays, which files are deleted.

### Examples

#### Example: 1

``DEL` FILE1.EXT FILE2.EXT`
Deletes the files `FILE1.EXT` and `FILE2.EXT`.

#### Example: 2

``DEL` /P *.bak`
Deletes all files with extension `BAK`, but prompts the user for each single file before deleting it.

#### Example: 3

``DEL`.`
Deletes all files within the current directory.

## DIR - Displays the contents of the directory

See also: CHDIR, MKDIR, RMDIR
Requirements: CMD_DIR

### Synopsis

`DIR` [{ options | pattern }]

``DIR`` displays the contents of direcories and/or the attributes of files, whatever the `pattern` specifies. If no `pattern` is specified on command line, the current working directory is displayed. The actual information displayed depends on the specified options and is explained below.

A `pattern` may contain wildcards, which are expanded against both files and directories. To specify a directory is essentially equal to write: `directory\*.*`.

Unlike options patterns are performed in sequence, that means that if two patterns are specified, first all entries matching the first one, then all entries matching the second one are displayed; instead of to display the matching entries intermixed.

Before parsing its command line `DIR` parses any option specified by the environment variable `DIRCMD`.

### Options

Unless stated otherwise all options of this command do follow the standard rules for options.

- `/A`: (All) Wildcards are matched against System and Hidden files, too.
- `/A**`: (Attribute) Wildcards are matched against files with selected attributes set or clear. The argument of the `/A` option is a sequence of:
  - `?` meaning: attribute `?` must be set, or
  - `-?` meaning: attribute `?` must not be set.

  The following attributes, the `?` above, are supported:

  - `R` for: read-only,
  - `H` for: hidden,
  - `S` for: system,
  - `D` for: directory, and
  - `A` for: archive.

  If the same attribute is specified twice within the same `/A` option, the last one superceeds previous ones; if more than one `/A` option is specified, the last one superceeds all previous ones.

- `/B`: (Bare) Displays the lines with the information of files and directories only. The ones displaying the volume label, the serial number, totals etc. are suppressed. In combination with `/S` the absolute path of the files is displayed.
- `/L`: (Lower-case) Filenames are displayed in lower-case letters rather than capitol ones.
- `/O`: (Order default) is a synonym of `/ONG`.
- `/O**`: (Order) Sort the entries displayed in a specific order. The following sort orders are supported:
  - `D` sort by last modification date (earliest first)
  - `E` sort by file extension
  - `G` group directories first
  - `N` sort by file name
  - `S` sort by size (smallest first)
  - `U` do not sort (unsorted)

  Each sort order, except `U`, may be prefixed by a hyphen to reverse the sort order. `U` effectively cancels any previous setting or specified sort order, e.g. to override an `/O` option from the `DIRCMD` environment variable.

  If the same sort order is specified twice within the same `/O` option, the last one superceeds previous ones; if more than one `/O` option is specified, the last one superceeds all previous ones.

  Warning: The entries are cached within memory before displaying them; if FreeCOM runs short on memory, to sort is disabled completely or the entries are sorted in chunks only.

- `/P`: (Page) Page the output -- pause the display after issuing one screen-full.
- `/S`: (Subdirectories) Recursively display directories.
- `/W`: (Wide) Displays five filenames per line and suppress the information about the file size, date etc.
- `/Y`: (Year) Displays a 4-digit year, rather than just two digits.
- `/4`: (4digit Year) is a synonym of `/Y`.

### Examples

#### Example: 1

``DIR``
Displays the contents of the current directory, but ignore System and Hidden files. The output may look like this:

    !!todo!!

#### Example: 2

``DIR` a* bb* *.txt`
First displays all files, that begin with the letter `A`; then all files, that begin with two letters `B`, are displayed and at last all files with the extension `TXT`.

#### Example: 3

``DIR` /w a* b*`
``DIR` a* /w b*`
``DIR` a* b* /w`
Because the position of options is not significant, all these examples behave the same way and display the matching files in wide or also called short form, which may look like this:

    !!todo!!

## DIRS - Display the directory stack

See also: CD, CHDIR, POPD, PUSHD
Requirements: CMD_DIRS

### Synopsis

`DIRS`
Displays all directories stacked with the `PUSHD` command.

## ECHO - Displays a string onto screen

See also: TYPE
Requirements: CMD_ECHO

### Synopsis

1. `ECHO` [ `ON` | `OFF` ]
2. `ECHO` «string»
3. `ECHO.`

When executing a batch script each line is displayed to the console before executing it by default. The first variant of `ECHO` enables or disables this behaviour. To disable echoing the commands is equal to prefix each line of a batch script with the Ad-symbol `@`.
If `ECHO` is invoked with no argument at all, the current echo status is displayed.
When entered on an interactive command line the echo status controls whether or not the `PROMPT` string is displayed.

The second variant displays the specified «string».
Note: Because of variant 1 «string» may not expand to the single words `ON` or `OFF` without another character.

The third variant displays an empty line. No space must be placed between the dot and `ECHO`.

### Examples

#### Example: 1

``ECHO``
Displays the current echo status, e.g. responding:

    ECHO is on

#### Example: 2

`@`ECHO` OFF`
Disables the echo status. Because the Ad-sign `@` disables the echo status right for this line, this command disable echoing all the next lines of a batch script and is not echoed to the console itself. It is, therefore, best placed in the first line of a batch script.

#### Example: 3

``ECHO` Just a text`
Displays `Just a text`

## FEATURE_ENHANCED_INPUT - Enhanced command line editing

See also: FEATURE_FILENAME_COMPLETION, FEATURE_HISTORY

If enabled on compilation of FreeCOM, enhanced command line editing features are activated. Otherwise, FreeCOM uses the default buffered input DOS API function #0A.

If this feature is disabled, neither command line history nor filename completion is available.

Besides the other features various key bindings recognized, which are listed in the general FreeCOM documentation.

## ERASE - Delete files

This command is 100% compatible to DEL, please see there

## EXIT - Terminate shell

### Synopsis

`EXIT`
Terminates the currently running shell, unless FreeCOM had been started with the `/P` option. In this case, `EXIT` works like `CANCEL`.

## FEATURE_AUTO_REDIRECT_TO_CON - Autoswitch CON: to monitor

If defined on compilation of FreeCOM and if FreeCOM is to terminate although it is forbidden -- e.g. by passing the `/P` option when executing FreeCOM --, the console is changed to the keyboard/monitor pair automatically after some insuccessful prompts to reboot the system.

### Options

Compile-time options:

- ``FEATURE_AUTO_REDIRECT_TO_CON``: How many loops may pass before switching the console CON: to the monitor. Default: 5.

## FEATURE_BATCH - Batch script processing

Requirements: IMPLICIT

The batch script processing is always enabled.

### Options

Compile-time options:

- `BATCH_NESTLEVEL_MIN`: Minimal supported batch nesting level. Default: 5

## ENVIRONMENT_KEEP_FREE - keep free space in environment segment

If defined on compilation of FreeCOM, FreeCOM tries to keep the unused space in the environment segment equal to or greater than ``ENVIRONMENT_KEEP_FREE``. The default value is 256.

## FEATURE_BOOT_KEYS - check for F5/F8 keys on startup if /P is present

If defined on compilation of FreeCOM, FreeCOM waits three seconds on startup, if the `/P` switch is present. If during this time a key has been pressed, `F5` will bypass AUTOEXEC.BAT execution and `F8` will enable trace mode.
`F5` is equal to to pass the `/D` switch to FreeCOM.
`F8` is equal to to pass the `/Y` switch to FreeCOM.

## FEATURE_INSTALLABLE_COMMANDS - Installable Commands interface (MUX-AE)

If defined on compilation of FreeCOM, calls to the Installable Commands API are made before executing any command. The API is situated at MUX-AE, the Multiplexer interrupt 0x2F function 0xAE.

The interface is documented elsewhere, for instance RBIL (Ralph Brown's interrupt list).

## FEATURE_NLS - use DOS NLS

If defined on compilation of FreeCOM, FreeCOM uses the information retrievable by the currently active DOS NLS using the API functions #65.

These information influence:

- the format displaying time and date information,
- the characters to delimit items in lists,
- the currency string and display format,
- how to up- (and supported by some NLS only) to lower-case characters,
- how to sort characters.

## FEATURE_CALL_LOGGING - Startup logging

If defined on compilation of FreeCOM, all startups of a FreeCOM instance is logged into a file.

The drive the logfile is created on can be changed at run-time with the external tool `PTCHLDRV`.

### Options

Compile-time options:

- `LOG_FILE`: The name of the logfile. Default: `C:\FreeCom.log`

## FEATURE_FILENAME_COMPLETION - Filename completion

Requirements: FEATURE_ENHANCED_INPUT

If defined on compilation of FreeCOM and if the enhanced command line editing is activated as well, the tabulatur key binding becomes available.

When the tabulator key is pressed, the word the cursor is located on actually or is immediately preceeding is separated and tried to match against files, like a `DIR` command would do, e.g. when hitting tab at the command line:
`bar\f_ some arguments`
-- where the underscore `_` is to mark the location of the cursor and is no actual character -- causes FreeCOM to try to locate any files or directories matching the filename pattern `bar\f*.*`.
If none is found, a beep is issued to indicate that error and the command line remains unchanged.
Otherwise as many characters are appended to the filename as are the same for all found matches, e.g.:

1. if exactly one match was found, its name is appened.
2. if, for example, the files or directories: `FOO`, `FUU.TXT` or `FUU` are present in the directory `BAR`, no character is appened, because there are no equal characters following the already present `f` character.
3. if, for example, the files or directories: `FOO`, `FOO.TXT` or `FOO1.TXT` are present in the directory `BAR`, the two characters `OO` are appened, because all found matches share these two characters immediately following the already present characers. Hence, the command line is expanded to:
   `bar\FOO_ some arguments`
   Please note that the case of all characters will match the case of the retrieved filenames.

In addition, because in the cases 2 and 3 the file completion was not complete because more than one match was found, a beep is issued. In this situation to hit the tabulator key a second time, without an intervueing other key press, causes to display all available matches, but keeps the command line unchanged otherwise.
If exactly one filename match was found, hence the file completion was complete, and if the found match is a directory, a backslash is appended to. This allows to walk into deep levels of directories speededly.

If the cursor had been placed, for instance, under the backslash in above mentioned command line, the full string `bar\f` had been tried to be completed as well. This behaviour differs from other implementations.

### Options

Compile-time options:

- `FILE_SEARCH_MODE`: Filemode passed to the DOS API to aquire matching directory entries. Default: Read-Only, Archive, Directory

## FEATURE_DIRSTACK - Directory stack

See also: DIRS, POPD, PUSHD

This feature is automatically enabled, if `PUSHD` is enabled.

The directory stack pushes and pops directories on demand via the commands `PUSHD` and `POPD`. `DIRS` displays all pushed directories.

Please see the documentation of the mentioned commands.

### Options

Compile-time options:

- `DIRSTACK_DEFAULT_SIZE`: The amount of bytes reserved to store items of the directory stack. Default: 256

## FEATURE_HISTORY - Command line history

See also: HISTORY
Requirements: FEATURE_ENHANCED_INPUT

If enabled on compilation of FreeCOM and the enhanced command line editing is acivated as well, the command line history becomes available.

When commands are enterred manually on the command line prompt of FreeCOM, old command lines are storred in the history and can be retrieved later using the key bindings of `F3`, `F1` and the cursor Up and Down keys.
Without the command line history at most one line is cached.

The command:
``HISTORY``
displays all cached command lines.

The command:
`HISTORY` number
resizes the amount of bytes reserved to cache command lines to `number` bytes. Doing so all cached command lines are deleted.

Each instance of FreeCOM maintains its own command line history, which is initially inherited from the particular parent instance, if any.

### Options

Compile-time options:

- `HISTORY_DEFAULT_SIZE`: The amount of bytes reserved initially. Default: 256

## FEATURE_LAST_DIR - Change back to last directory

See also: CD, CDD, CHDIR, POPD, PUSHD

If defined on compilation of FreeCOM, every change of the current directory using an internal command records the previous directory and enables the `-` shortcut for `CD`, `CDD` and `CHDIR`.

#### Example:

`C> `CD` \`
`C> `CD` freedos\bin`
`C> `CD` -`
`C> `CD` -`
The first `CD` command changes into the root direcotry, the second into the directory `\FREEDOS\BIN`, any subsequent ``CD` -` commands will change between the root directory and `\FREEDOS\BIN`.

## FOR - Repeat a command

Requirements: CMD_FOR

### Synopsis

`FOR` `'%'` letter `IN` `'('` { word | pattern } `')'` `DO` «any command»
Executes «any command» for several values assigned to the variable `letter`. The values are read strictly left to right from the `word`s and `pattern`s enclosed in parenthises; where `pattern`s are words containing wildcards and are replaced by all matching filenames.

Any occurence of a percent sign `%` and the specified letter is replaced by the current value of the `FOR` loop. Note: The letter is case-sensitively matched!

Warning #1: Unlike most commands I/O-redirections are passed forth to the command instead of to apply them to `FOR` itself, e.g.:
``FOR` %a IN (*.*) DO `ECHO` %a >q`
repeatedly executes the `ECHO` command with the redirection `>q`, hence, effectively overwriting the file each time.
Warning #2: Due the syntactical problem that the `FOR` variable is specified as `'%'` letter, which is also a legal start of an environment variable, the following kludge had been included to support `FOR` and its special variables:

- You can use as many percent character as you wish as long as you use exactly the same number for a particular `FOR` variable.
- Before any environment variables are expanded, the command line is checked for the skeleton specified within the synopsis (there must not be specified no redirection between the `FOR` and DO keywords), if it is found, the `FOR` command is executed without expanding any environment variables -- they get expanded each time the command is invoked.
- Known Bug: Otherwise any environment variables are expanded and, if it happens that a valid `FOR` command is found now, the environment variables within the command are expanded a second time. In this case the I/O redirections are applied to `FOR`, too, instead of passing them forth to the command.
- `FOR` commands as part of the command of `CALL`, `IF`, and `FOR` itself are never found before expanding the environment variables.

Warning #3: Due a bug in MS COMMAND (BugID #1050) the right parenthesis must be followed by at least one whitespace, this allows the "feature" to embed such characters within the words and patterns, e.g.:
``FOR` %a in (a()a b()b) DO command`
executes the `command` two times, first replacing `%a` by `a()a`, second by `b()b`.

### Examples

#### Example: 1

``FOR` %z IN (*.*) DO copy %a a:`
Performs a ``COPY` xyz A:` command for each file in the current directory. Its behaviour is equal to ``COPY` *.* A:`

#### Example: 2

``FOR` %z IN (a?b*.TXT) DO `CALL` batch arg %z`
Executes the batch script `batch.bat` for each file matching the pattern `A?B*.TXT` located in the current directory. Within the script, the automatic variable `%1` always expands to the constant argument `arg`, whereas `%2` expands to the filename of the current loop.

#### Example: 3

``FOR` %a IN (1 2 3 4 5) DO `ECHO` %a`
Is equal to the command sequence:
``ECHO` 1`
``ECHO` 2`
``ECHO` 3`
``ECHO` 4`
``ECHO` 5`
Because these words do not contain no wildcards, they are not matched as filenames.

#### Example: 4

``FOR` %g IN (1 2 3*) DO `ECHO` %g`
Performs the commands:
``ECHO` 1`
``ECHO` 2`
and the `ECHO` command for each file in the current directory, that has no extension and which name starts with the digit three.

## GOTO - Goto label

Requirements: CMD_GOTO

### Synopsis

`GOTO` [ `':'` ] label
Normally all commands of a batch script are executed in the sequence in which they are appear with the script. `GOTO` controls the command flow by unconditionally jumping to the specified `label`; the commands following that label will be executed then. A label is written as a colon in the first column of a line and the name of the label immediately behind. If FreeCOM hits a label in the normal flow, it is ignored completely, even any redirection characters are ignored.

The `label` must be located in the same script file as the `GOTO` itself, if it appears more than once, the first occurance takes precedence.

Conditional jumps can be contructed with help of the `IF` command, see example 2.

### Examples

#### Example: 1

``GOTO` ende`
Jumps the to label `:ende`

#### Example: 2

``IF` "%1"=="" `GOTO` emptyCommandLine`
Jumps to label `:emptyCommandLine`, if no argument had been passed to the batch script. For instance:

    @ECHO OFF
    IF "%1"=="" GOTO error
    REM do something sane here
    GOTO ende

    :error
    ECHO You must pass an argument to me!

    :ende

## HISTORY - Display command line history

Requirements: FEATURE_HISTORY

### Synopsis

1. `HISTORY`
2. `HISTORY` number

The first format without any argument displays all cached command lines.

The second format resizes the memory pre-allocated for the command line history cache to `number` bytes.

## IF - Conditional execution of a command

### Synopsis

1. `IF` [ `NOT` ] `EXIST` file «command»
2. `IF` [ `NOT` ] `ERRORLEVEL` number «command»
3. `IF` [ `NOT` ] string `'=='` word «command»
4. `IF` [ `NOT` ] quoted-string `'=='` quoted-string «command»

Conditionally executes the specified «command». If the keyword `NOT` is specified, the condition is negated, meaning, the «command» is executed, if the condition evaluates to false.

The first condition evaluates to true, if the specified `file` exists. Wildcards are supported. On local file systems one can test for character devices, too.

The second variant evaluates to true, if the errorlevel is currently assigned to a number greater or equal than the specified `number`. Errorlevels are assigned when external commands terminates or via `CANCEL` or `QUIT`.
Due to compatibly with other DOS shells FreeCOM does not check, if the specified errorlevel is a number, but silently accepts any string. This allows to use the so-called Benny levels, where you can specify `HA`, `HB`, ... , `HZ` or `xa`, `xb`, ... , `xz` instead of `1`, `2`, ... , `26`. Some malformed batch script use this syntax to make mapping of errorlevels to drive letters more visible. See example 5.

The third and four ones are true, when the left string is case-sensitively equal to the string on the right side of the double equal sign. Either side may be quoted by double quotes, though, if the right side is not quoted, the first word is tested only.

### Examples

#### Example: 1

``IF` NOT EXIST c:\command.com `ECHO` There is no COMMAND.COM in C:\`
Executes the `ECHO` command, if a file `C:\COMMAND.COM` does not exist.

#### Example: 2

``IF` EXIST c:\fdos\nul `GOTO` have_fdos_directory`
Branch the interpretation of the batch script to the label, if the file `C:\FDOS\NUL` exists. Because the filename `NUL` corresponds to the character device `NUL:`, which always exists, this test may be used to probe for the existance of the path `C:\FDOS`, because all character devices are virtually present in every directory of local filesystems.

#### Example: 3

``IF` %1==name `ECHO` First argument is "name"`
`ECHO` is executed, if the first argument of the current batch script is `"name"` (without the quotes). `%1` may expand to any string, even with embedded whitespaces, but without an embedded double equal sign. Also, metacharacters included within the argument are evaluated.

#### Example: 4

``IF` "%1"=="first name" `ECHO` First argument is "first name"`
`ECHO` is executed, if the first argument of the current batch script is `"first name"` (without the quotes). `%1` may expand to any string, even with embedded whitespaces or an embedded double equal sign or metacharacters.

#### Example: 5

«program»
``SET` drv=`
``FOR` %%Z IN (A B C D E F G H I J K L M N O P Q R S T U V W X Y Z) DO `IF` ERRORLEVEL H%%Z `SET` drv=%%Z`
``IF` ERRORLEVEL 27 `SET` drv=`
``IF` "%drv%"=="" goto error_no_drive_letter`
Assuming that «program» is setting the exit code to 1..26 for the drive letter, e.g. when searching for RAMdisks, this code snippet assigns the drive letter to the environment variable `drv` or unsets the variable on error.

Note: The following code is equal to the above one and fully compatible to all shells: «program»
``SET` drv=`
``IF` ERRORLEVEL 1 `SET` drv=A`
``IF` ERRORLEVEL 2 `SET` drv=B`
``IF` ERRORLEVEL 3 `SET` drv=C`
...
``IF` ERRORLEVEL 25 `SET` drv=Y`
``IF` ERRORLEVEL 26 `SET` drv=Z`
``IF` ERRORLEVEL 27 `SET` drv=`
``IF` "%drv%"=="" goto error_no_drive_letter`

## FEATURE_LOAD_MESSAGES - Load messages permanently

If enabled on compilation of FreeCOM, the `/MSG` becomes available.

If this option is present, when an instance of FreeCOM is created, the FreeCOM messages are loaded into memory permanently. Otherwise, the messages are loaded on demand and are removed from memory when an external command is executed, in order to conserve memory.

This feature may help to run FreeCOM on disk- and floppyless boxes.

## LOADFIX - Load an external program above the first 64KB memory

See also: CALL, LOADHIGH

### Synopsis

`LOADFIX` program [{ argument }]
Loads and executes an exepacked program, that would abort execution with the error message "Packed file corrupt" otherwise.

Attention: This command is not available in the XMS-only variant of FreeCOM!

#### Example:

``LOADFIX` program.exe`

## LOADHIGH - Load an external program into high memory

See also: CALL, LOADFIX

### Synopsis

`LOADHIGH` [{ option }] program [{ argument }]
Loads and executes an external program in high memory, also called UMB. This command is used to load TSRs, such mouse drivers, into the upper memory to conserve the conventional memory for programs.

#### Example:

``LOADHIGH` lmouse.com`

## MD - make directory

See also: CD, MKDIR, RD
Requirements: CMD_MKDIR

### Synopsis

`MD` path
Creates a directory of the specified name `path`. Any parent directories must already exist.

### Examples

#### Example: 1

``MD` C:\1`
Creates the directory `1` in the root directory of drive `C:`.

#### Example: 2

``MKDIR` C:\1\2\3`
Creates the directory `3` in the directory `\1\2` of drive `C:`. If the directory `C:\1\2` does not exist, yet, the command fails.

## MEMORY - Display the internally used memory

Requirements: CMD_MEMORY

### Synopsis

`MEMORY`

Displays the useage of internal memory of FreeCOM. Note: The internals of FreeCOM are currently under heavy construction, the actual output might vary heavily from this example.

### Examples

``MEMORY``
may display this:

    Environment segment    : max  1200 bytes; free     8 bytes
    Context segment        : max  2304 bytes; free  2252 bytes
            Aliases        : limit  1024 bytes, current     5 bytes,     0 items
            History        : limit   256 bytes, current    34 bytes,     2 items
            Directory stack: limit   256 bytes, current     5 bytes,     0 items
            Last dir cache : used      0 bytes,     0 items
            Swapinfo       : used      0 bytes,     0 items
    Heap                   : free 482080 bytes

- The `Environment segment` is the storage area, the environment variables are storred in. It may be changed passing the `/E` option to FreeCOM.
- FreeCOM stores several internal information into the `Context segment`; the aliases - modified by the `ALIAS` command -, the history - displayed using the `HISTORY` command, accessed by pressing the cursor Up/Down keys on command line -, the directory stack - displayed with the `DIRS` command and accessed using the `PUSHD` and `POPD` commands -, the last directory - accessed with the ``CD` -` command -, and, finally, some internal command used by the low-level swap interface of FreeCOM.
- The `heap` is the storage area FreeCOM can allocated memory from itself. This value is useful for FreeCOM developers mostly.

- `max` specifies the maximum amount of bytes allocatable within this storage area.
- `free` specifies the unused bytes within this storage area.
- `limit` specifies the maximum amount of bytes allocatable for the particular information within the area.
- `current` specifies the amount of bytes currently allocated for the particular information.
- `items` specifies the number of items storred for the particular information, e.g. how many directories have been pushed onto the stack using `PUSHD`.

## MKDIR - Make directory

This command is 100% compatible to MD, please see there

## PATH - Display or set the search path

Requirements: CMD_PATH

### Synopsis

1. `PATH`
2. `PATH` [ `'='` ] { path : `';'` }
3. `PATH;`

Displays or assigns a new search path.

The first variant displays the currently active search path.

The second one assigns the specified paths to the search path. The leading equal sign, if present, is ignored.

The third variant empties the search path.

When FreeCOM searches for an external command or a batch script, which has no path specified, it is search for in all the directories specified in the search path. If the current directory `.` is not mentioned in the search path, it is searched through first.

### Examples

#### Example: 1

``PATH` c:\fdos\bin;c:\tools;d:\others\bin;bin`
If FreeCOM is to execute an external program, e.g. `XCOPY`, FreeCOM will search for the program in the following directories in the specified order, the first program file found is executed:

1. the current directory
2. `C:\FDOS\BIN`
3. `C:\TOOLS`
4. `D:\OTHERS\BIN`
5. `BIN`

Note: Because the last directory specification is a relative one, rather than an absolute one, the program is searched for in the sub-directory `BIN` of the current directory.

## PAUSE - Pauses batch file execution

Requirements: CMD_PAUSE

### Synopsis

1. `PAUSE`
2. `PAUSE` «string»

Pauses the batch file execution until a key is pressed.

``PAUSE`` prompts the user with the specified string or, if none is specifed, "`Press any key to proceed`"

### Examples

#### Example: 1

``PAUSE``
Just pauses the execution.

#### Example: 2

``PAUSE` Execution paused, press any key to proceed ...`
Pauses execution displaying this string.

#### Example: 3

``PAUSE` >nul`
Pauses execution, but does not display any prompt.

## POPD - Change back to the last pushed directory

See also: CD, CDD, DIRS, POPD
Requirements: CMD_CDD, CMD_POPD

### Synopsis

1. `POPD`
2. `POPD` `'*'`

The first variant changes the current directory back to the one, in which the last `PUSHD` command was executed.

The second one clears all entries of the directory stack, but does not change the current directory.

## PROMPT - Display or set the shell prompt

Requirements: CMD_PROMPT

### Synopsis

`PROMPT`
`PROMPT` [ `'='` ] prompt

### Options

Unless stated otherwise all options of this command do follow the standard rules for options.

### Examples

#### Example: 1

## PUSHD - Push the current working directory onto the directory stack

See also: CD, CDD, DIRS, POPD
Requirements: CMD_CDD, CMD_PUSHD

### Synopsis

`PUSHD` directory

### Options

Unless stated otherwise all options of this command do follow the standard rules for options.

### Examples

#### Example: 1

## QUIT - Terminate the current script

### Synopsis

`QUIT` [ n ]
Terminates the current active batch script and, if present, assigns the specified number `n` to the errorlevel.

Note: This command is a hidden internal command.

## RD - Remove directory

See also: CD, MD, RMDIR
Requirements: CMD_RMDIR

### Synopsis

`RD` path

### Options

Unless stated otherwise all options of this command do follow the standard rules for options.

### Examples

#### Example: 1

## REM - Marks comments or remarks in batchfiles

Requirements: CMD_REM

### Synopsis

`REM` «string»

### Options

Unless stated otherwise all options of this command do follow the standard rules for options.

### Examples

#### Example: 1

## REN - Rename files

See also: RENAME
Requirements: CMD_RENAME

### Synopsis

`REN` «source» «destination»
Renames the source file(s) into the target file(s). See also: \REF{wildcards}

The «destination» must not contain any path specification, the «source» file is renamed within the directory it is currently located in, see example 2 below. Any wildcards used within «destination» are replaced by the corresponding character of the source filename, see example 4 below.

### Options

Unless stated otherwise all options of this command do follow the standard rules for options.

### Examples

#### Example: 1

``REN` file1.txt file2.txt`
Renames `file1.txt` into `file2.txt`

#### Example: 2

``REN` path\file1.txt file2.txt`
Renames `path\file1.txt` into `path\file2.txt`

#### Example: 3

``REN` path\file*.txt *.bak`
Renames all files located within directory `path` with extension `.txt` and which filename is beginning with `file`, such as `file.txt`, `filea.txt` and `file99xx.txt`, into `*.bak` files.

#### Example: 4

``REN` *.DAT A*.*`
Renames all files located within the current directory with extension `.DAT` into files by replacing the very first character of the filename by the letter `A`, all other characters, the file extension and path are remain unchanged.

#### Example: 5

``REN` *.TXT ??b*.bak`
Renames all files located within the current directory with extension `.TXT` into files by replacing the third character of the filename by the letter `B` and the file extension to `.BAK`, all other characters and the file path are remain unchanged.

Warning: If the source file name consists of one character only, the second question mark in the destination pattern is ignored, hence, e.g. the file `A.TXT` is renamed into `AB.BAK` by this example, what is incompatible to MS COMMAND v6.22 (maybe others, too), which embedds a space as second character making the file inaccessable, but what is exactly the same behaviour of the same MS COMMAND's `COPY` command.

## RENAME - Rename files

This command is 100% compatible to REN, please see there

## RMDIR - Remove directory

This command is 100% compatible to RD, please see there

## SET - Display or set environment variables

Requirements: CMD_SET

### Synopsis

1. `SET` [{ option }]
2. `SET` [{ option }] variable `'='` «string»

The first variant (without any argument) displays all the currently defined environment variables in the format (without any whitespaces before or after the equal sign): name `'='` «value»

The second variant assigns a new value «string» to the specified variable. If the variable already exists, the old value is overwritten without notice; otherwise it is newly created.

### Options

Unless stated otherwise all options of this command do follow the standard rules for options. All options must preceed the assigment, if present.

- `/C`: forces to keep the exact case of the letters of the variable name; by default all letters are uppercased to keep compatibly.
- `/I`: has been temporarily included to the `SET` command to allow an easy way to display the current size of the environment segment, because it is one of the most frequently reported, but not reproduceable bug report. Once this option has been encountered, all the remaining command line is ignored.
- `/P`: Prompts the user with the specified «string» and assigns the user's input to the variable. If no input is made, hence, one taps just `ENTER`, an empty value is assigned to the variable, which is then removed from the environment.

## SHIFT - Shift the arguments of a batch script

Requirements: CMD_SHIFT

### Synopsis

1. `SHIFT`
2. `SHIFT` `DOWN`

Shifts the arguments of a batch script one position up (first variant) or down (second variant).

Within a batch script the automatic variables %0 through %9 are replaced by the script name and the first nine arguments. This can be imagined as a window to ten arguments of the script. `SHIFT` will allow to move this window of ten arguments towards its end (up) or its start (down).

After `SHIFT` has been executed, the former %0 is hidden and inaccessable, %1 became %0, %2 became %1 a.s.o, %9 became %8 and the formerly hidden tenth argument became %9.
``SHIFT` DOWN` reverses one `SHIFT` command.

`SHIFT` can be called as many times as wanted, ``SHIFT` DOWN` won't allow to underflow the very first argument.

### Examples

#### Example: 1

If the batch script B.BAT:
`@`ECHO` OFF`
``ECHO` 0: %0`
``ECHO` 1: %1`
``ECHO` 2: %2`
had been executed using:
`B.BAT 1 2 3 4`
it displays:

    B.BAT
    1
    2

If a `SHIFT` command had been inserted as second line, the same call displays:

    1
    2
    3

## TIME - Display or set current time

See also: DATE
Requirements: CMD_TIME

### Synopsis

1. `TIME` [ /T ]
2. `TIME` [ /T ] time

Variant 1 displays the current time, then enters a loop prompting the user to enter a new time. The loops terminates when a valid time had entered or the user just pressed the `ENTER` key.

Variant 2 does not display the current time, but tries to change the current time to the specified `time`, on failure the loop as explained above is entered.

The individual portions of a time may be sperated by at least: dots `.`, colons `:` and forward slashes `/`. Other nationally used characters may be supported, too. If a certain number of portions are specified:

1. error,
2. hour:minute; seconds and hundreds default to zero,
3. hour:minute:seconds; hundreds defaults to zero,
4. hour:minute:seconds.hundreds;
5. more than 4 portions result in an error.

Separated by no, one or more whitespaces the am/pm modifiers may follow optionally. If present they alter the given time as follows:

- AM: if hour is equal to 12, it becomes 0 (midnight).
- PM: f hour is greater than 12, it is incremented by 12.

### Options

All options must preceed any arguments.

`/T`: prevents from prompting the user.

1. In variant 1, the time is displayed only.
2. In variant 2, the time is tried to be changed, but the loop is not entered on failure.

### Examples

#### Example: 1

``TIME` /T`
Just displays the current time.

#### Example: 2

``TIME` 18:2`
Sets the current system time to 6:02 PM.

## TRUENAME - Display the true name of a file

Requirements: CMD_TRUENAME

### Synopsis

`TRUENAME` path

### Options

Unless stated otherwise all options of this command do follow the standard rules for options.

### Examples

#### Example: 1

## TYPE - Display the contents of files

See also: DIR, ECHO
Requirements: CMD_TYPE

### Synopsis

`TYPE` { pattern }

### Options

Unless stated otherwise all options of this command do follow the standard rules for options.

### Examples

#### Example: 1

## VER - Display the version information about FreeCOM and DOS

Requirements: CMD_VER

### Synopsis

`VER` [{ option }]

### Options

Unless stated otherwise all options of this command do follow the standard rules for options.

### Examples

#### Example: 1

## VERIFY - Display or set verify level

Requirements: CMD_VERIFY

### Synopsis

`VERIFY` [ `ON` | `OFF` ]

### Options

Unless stated otherwise all options of this command do follow the standard rules for options.

### Examples

#### Example: 1

## VOL - Display the volume label of a drive

See also: DIR

### Synopsis

`VOL` [ drive ]

### Options

Unless stated otherwise all options of this command do follow the standard rules for options.

### Examples

#### Example: 1

## WHICH - Search and display the executable file of specified commands

Requirements: CMD_WHICH

### Synopsis

`WHICH` [{ command }]

Searches for the specified command(s) the same way as if it would be specified on command line as command itself. If an executable file is found, its path is displayed in this format:
command «tab» path
The «tab» stands for the tabulator character (ASCII 9).
If the command is not found only the command part, but neither a path nor the «tab» is displayed.

Internal commands, installable commands and aliases are not found.

### Examples

#### Example: 1

``WHICH` which`
Returns a file or nothing, because `WHICH` is an internal command.

#### Example: 2

``WHICH` command`
Could display for instance:

    command	C:\COMMAND.COM

Please note that `command` is the string "command" and no placeholder.

## Appendix

### Current Directory

The current directory is the default directory of a drive.

DOS stores a default directory for each drive. When a path is specified with a drive specification only, such as `D:`, it is completed with this default directory of that drive to construct the absolute path to be used.

### Current Working Direcory

In opposite to the current directory the current working directory is the absolute path constructed out of the currently selected drive and current directory of that drive.

### Path Specification

In DOS an absolute path is constructed out of several components:

1. drive,
2. directory,
3. filename, and
4. file extension.

like this: `D:\DIR1\DIR2\FILENAME.EXT`.

The drive is a single letter from `A` through `Z` followed by a colon `:`.

The remaining part of a path consists of similiar components delimited by a single backslash `\`. The last component is also called filename. Each of these components may be formed of a name, up to eight characters long, and an extension, up to three characters long. Both parts are delimited by a single dot `.`. Although the extension may be absent, the filename must have at least one character.
Note: The term filename is not limited to files in the usual sense, but may apply to any name visible in a directory, such as subdirectories and volume labels, as well.

To ease the way to enter a path the user may specify a relative path, rather than an absolute one. In such path one or more components may be missing:

- If no drive is specified, what means that no colon is specified, the path is prefixed by the currently selected drive.
- If the directory is not prefixed by the backslash or no directory is specified at all, the current directory of the drive is inserted right behind the colon.
- Some programs may append an absent extension to the very last filename component.

Examples, assume the current directories of

Drive | Current Directory
C: | `\FREEDOS\HELP`
D: | `\TEMP\TEXT`

The currently selected drive is `C:`.

1. `C:\`
   The root directory of drive `C:`.
2. `.`
   The current working directory, ergo: `C:\FREEDOS\HELP`.
3. `..`
   The parent directory, ergo: `C:\FREEDOS`.
4. `D:`
   The current directory of drive `D:`, ergo: `D:\TEMP`.
5. `D:.`
   The current directory of drive `D:`, ergo: `D:\TEMP`.
6. `D:..`
   The parent directory of drive `D:`, ergo: `D:\`.
7. `..\BIN`
   Because there is neither a drive nor a leading backslash, both the currently selected drive and the current directory of that drive is inserted before the given path, ergo: `C:\FREEDOS\HELP\..\BIN`.
   The embedded component `..` has the same meaning as when specified alone: parent directory, though, here in the context of the directory `C:\FREEDOS\HELP\`. That means that the final absolute path is: `C:\FREEDOS\BIN`.

Path specifications that do not conform to above mentioned format lead to various different behaviour of the various programs, because there is no standard to scan, parse and interprete such patterns. Problems include:

- multiple backslashes,
- multiple dots,
- multiple colons, or a colon at a position unequal to two,
- The current directory `.` or parent directory `..` special directories in the context of a root directory, such as `C:\.`, `C:\..`, or `C:\TEMP\..\..`.

Note: The special directories `.` and `..` are no phantom directories or virtual entries, but standard entries of every directory except the root directories. These entries help crash recovery tools, such as `CHKDSK` or `SCANDISK`, to find errors within the directory structure and restore it to a valid file tree. Therefore a common assumption that a tripple dot `...` directory means parent-of-parent is incorrect, though, might be supported by certain programs.

### Standard Rules for Options

Options are prefixed by one forward slash "`/`", the following character identifies the option and is called option character, for instance: `/A`

Some commands do accept long option names, where a complete word identifies the option rather than a single character, e.g. `/MSG`.

Some option may be used in conjunction with an argument. The argument is appended to the option with one colon "`:`" or one equal sign "`=`", for instance: `/A:hr` or `/P=fdexec.bat`.

Multiple options without argument maybe merged together as a single option with or without embedded slashes, e.g. `/WS` or `/W/S`, instead of `/W /S`.
However, because some commands do accept long option names, the way with embedded slashes is more secure and is recommended therefore.
An option with argument may be the last one of such merged options.

Options without arguments enable or disable certain features. Therefore, those options are sometimes called boolean options or flags.
Boolean options may be optionally prefixed by a plus "`+`" or minus "`-`" sign. So, the boolean option `O` can be written in three ways:

1. `/+O`: The option is enabled.
2. `/-O`: The option is disabled.
3. `/O`: (neither plus nor minus sign) The option is toggled or flipped; this means if the option is enabled currently, it is disabled; but if it is disabled currently, it is enabled.

Without user invention a boolean option is disabled by default, so both `/+O` and `/O` behave the same most of the time. However, some commands allow the user to change the default settings of certain options, e.g. `COPY` and `DIR`.

### I/O Redirection

In DOS the standard input and output can be redirected to a file or another device; however, although it is common to use these I/O streams today, some programmers cowardly ignore them for reasons of speed or program size.

If the input stream is redirected to a file or device, instead of polling the keyboard and request the user to interactively enter characters via the keyboard, those characters are read from the file or device. Usually these programs terminate when the file has been read wholely.

If the output stream is redirected to a file or device, instead of issuing the information onto screen, it is dumped into the file or device. Per convention each program has two output streams: one (called standard output) to issue normal information and one (called standard error output) for error messages the user should not miss.

Redirections are specified on command line and effect exactly that command invoked herein, regardless if the command is an external or internal one, an alias or batch script. The utter exception is the `FOR` command, which requires that the redirection is to apply to the command specified behind the DO keyword rather than `FOR` itself.
If more than one redirection is specified on the command line and they effect the same stream (input, output, or error), the rightmost one superceed any previous one.

Redirections are syntactically specified like this:
operator target
operator ::= `'<'` | `'>'` [ `'>'` ] [ `'&'` [ `'>'` ] ]
target ::= file | device
Although it is not relevant where the redirections are placed on the command line, it is common praxis to place them at the end of it.

The `operators` have the following meaning:

Operator | Redirection
--- | ---
`<` | Input stream
`>` | Output stream; target file is overwritten
`>>` | Output stream; output is appended to target, if it already exists
`>&` | Output and error stream; target file is overwritten
`>>&` | Output and error stream; output is appended to target, if it already exists
`>&>` | Error stream; target file is overwritten
`>>&>` | Error stream; output is appended to target, if it already exists

### Examples

#### Example: 1

`cmd <in1 <in2`
Input stream is redirected to file `IN2`, because it is the rightmost one.

#### Example: 2

`cmd <in >&out`
Input stream is redirected to file `IN`, output and error streams are joined together and redireced into file `OUT`. If the file `OUT` already exists, the old contents is discarded and replaced by the new one; otherwise, the `OUT` is created anew.

#### Example: 3

`cmd <in >>&out`
As example 2, but instead of replacing the contents of `OUT`, if the file already exists, the new information is appended to the end of the file.

#### Example: 4

``FOR` %a IN (*.*) DO `ECHO` %a >out`
As mentioned earlier, `FOR` is an exception and passes forth the redirections to each invocation of the command specified right of the DO keyword. So this examples overwrites the output file each time the `ECHO` command is performed, thus, instead of creating a file list, only the last found file is recorded into `OUT`.

#### Example: 5

``IF` EXIST out `DEL` out`
``FOR` %a IN (*.*) DO `ECHO` %a >>out`
This sequence eliminate the problem, the `IF` command is required to actually replace the file rather than appending the file list to the probably existent file.

#### Pipes

Another form of redirection is piping. Hereby, the output stream of one command is connected to the input stream of another command. Pipes can combine any number of commands this way. Because DOS is no multitasking system, pipes are simulated by spawning the first command with an output redirection capturing the issued information into a temporary file and then the second command with an input redirection from that very same temporary file, on completation of the second command the temporary file is deleted.

### Examples

#### Example: 1

`cmd1 | cmd2 | cmd3`
Which is similiar to this sequence:
`cmd1 >%TEMP%\t1`
`cmd2 <%TEMP%\t1 >%TEMP%\t2`
``DEL` %TEMP%\t1`
`cmd3 <%TEMP%\t2`
``DEL` %TEMP%\t2`

#### Example: 2

The first and last command can have an input or output redirection respectively, like so:
`cmd1 | cmd2 | cmd3 <in >out`
Which is similiar to this sequence:
`cmd1 >%TEMP%\t1 <in`
`cmd2 <%TEMP%\t1 >%TEMP%\t2`
``DEL` %TEMP%\t1`
`cmd3 <%TEMP%\t2 >out`
``DEL` %TEMP%\t2`

#### Example: 3

The error stream can be piped as well:
`cmd1 |& cmd2 | cmd3`
Which is similiar to this sequence:
`cmd1 >&%TEMP%\t1`
`cmd2 <%TEMP%\t1 >%TEMP%\t2`
``DEL` %TEMP%\t1`
`cmd3 <%TEMP%\t2`
``DEL` %TEMP%\t2`
Here only the error messages of `cmd1` are passed into `cmd2`; the error messages of both `cmd2` and `cmd3` are issued to the screen.

#### Nested redirections

Batch scripts or when external programs invoke other programs or another shell, redirections may be nested, e.g.:

Consider the batch file `BATCH.BAT`:

    @ECHO OFF
    ECHO 1
    ECHO 2 >out_2
    ECHO 3

which is invoked via:
`BATCH >out_1`
When the script `BATCH` gets executed, the actual output stream is redirected to the file `OUT_1`. Therefore the output of the first `ECHO` command is redirected into this file.
Because the second `ECHO` command has its own output redirection, its output is redirected into the file `OUT_2`. On completion of `ECHO` the redirection is closed and the former one is restored.
What causes that the output of the third `ECHO` command is redirected into `OUT_1` again.

### Hidden Internal Commands

There are some special internal commands, that are not directly visible nor accessable. They are hidden because of two main purposes:

1. Many of them are of internal nature and should not used by the user.
2. They are extensions to the normal batch language and may, therefore, clash with a particular installation. To prevent this clash those commands are hidden by default and can be made directly accessable via the ICMD command.

Hidden internal commands can be access by prefixing the command with `::=`. This token usually specifies a label within the batch language, given the nature of the labels, they may be comments as well. Due to the latter variant, most non-FreeCOM shells won't see the `::=`, hence, ignore those commands.

For example: `C> ::=`CANCEL` 30`
cancels (terminates) all currently active batch files and assigns `30` to the current errorlevel.