# Appendix to the Description of Features and Implementation Status of FreeCOM

## 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 <CMD>D:</CMD>, 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: <CMD>D:\DIR1\DIR2\FILENAME.EXT</CMD>.

The drive is a single letter from <CMD>A</CMD> through <CMD>Z</CMD> followed by a colon <CMD>:</CMD>.

The remaining part of a path consists of similiar components delimited by a single backslash <CMD>\</CMD>. 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 <CMD>.</CMD>. 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: | <CMD>\FREEDOS\HELP</CMD>
D: | <CMD>\TEMP\TEXT</CMD>

The currently selected drive is <CMD>C:</CMD>.

1. <CMD>C:\</CMD>
   The root directory of drive <CMD>C:</CMD>.
2. <CMD>.</CMD>
   The current working directory, ergo: <CMD>C:\FREEDOS\HELP</CMD>.
3. <CMD>..</CMD>
   The parent directory, ergo: <CMD>C:\FREEDOS</CMD>.
4. <CMD>D:</CMD>
   The current directory of drive <CMD>D:</CMD>, ergo: <CMD>D:\TEMP</CMD>.
5. <CMD>D:.</CMD>
   The current directory of drive <CMD>D:</CMD>, ergo: <CMD>D:\TEMP</CMD>.
6. <CMD>D:..</CMD>
   The parent directory of drive <CMD>D:</CMD>, ergo: <CMD>D:\</CMD>.
7. <CMD>..\BIN</CMD>
   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: <CMD>C:\FREEDOS\HELP\..\BIN</CMD>.
   The embedded component <CMD>..</CMD> has the same meaning as when specified alone: parent directory, though, here in the context of the directory <CMD>C:\FREEDOS\HELP\</CMD>. That means that the final absolute path is: <CMD>C:\FREEDOS\BIN</CMD>.

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 <CMD>.</CMD> or parent directory <CMD>..</CMD> special directories in the context of a root directory, such as <CMD>C:\.</CMD>, <CMD>C:\..</CMD>, or <CMD>C:\TEMP\..\..</CMD>.

Note: The special directories <CMD>.</CMD> and <CMD>..</CMD> 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 <CMD>CHKDSK</CMD> or <CMD>SCANDISK</CMD>, to find errors within the directory structure and restore it to a valid file tree. Therefore a common assumption that a tripple dot <CMD>...</CMD> 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 "<CMD>/</CMD>", the following character identifies the option and is called option character, for instance: <OPT>/A</OPT>

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

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

Multiple options without argument maybe merged together as a single option with embedded slashes, e.g. <OPT>/W/S</OPT>, instead of <OPT>/W /S</OPT>.
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 prefixed by a minus "<CMD>-</CMD>" sign, in order to disable or turn off the option; otherwise, the option is enabled.
Without user invention a boolean option is disabled by default. 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:
EBNF: operator target EBNF: operator ::= '<' | '>' [ '>' ] EBNF: 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 <ARG>operators</ARG> have the following meaning:

Operator | Redirection
--- | ---
<CMD><</CMD> | Input stream
<CMD>></CMD> | Output stream; target file is overwritten
<CMD>>></CMD> | Output stream; output is appended to target, if it already exists

EXAMPLES: EXAMPLE: 1 CMD: cmd <in1 <in2
Input stream is redirected to file <CMD>IN2</CMD>, because it is the rightmost one. EXAMPLE: 2 CMD: cmd <in >out
Input stream is redirected to file <CMD>IN</CMD>, the output streams is redireced into file <CMD>OUT</CMD>. If the file <CMD>OUT</CMD> already exists, the old contents is discarded and replaced by the new one; otherwise, the <CMD>OUT</CMD> is created anew. EXAMPLE: 3 CMD: cmd <in >>out
As example 2, but instead of replacing the contents of <CMD>OUT</CMD>, if the file already exists, the new information is appended to the end of the file. EXAMPLE: 4 CMD: 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 <CMD>OUT</CMD>. EXAMPLE: 5 CMD: IF EXIST out DEL out CMD: 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 CMD: cmd1 | cmd2 | cmd3
Which is similiar to this sequence:
CMD: cmd1 >%TEMP%\t1 CMD: cmd2 <%TEMP%\t1 >%TEMP%\t2 CMD: DEL %TEMP%\t1 CMD: cmd3 <%TEMP%\t2 CMD: DEL %TEMP%\t2 EXAMPLE: 2 The first and last command can have an input or output redirection respectively, like so:
CMD: cmd1 | cmd2 | cmd3 <in >out
Which is similiar to this sequence:
CMD: cmd1 >%TEMP%\t1 <in CMD: cmd2 <%TEMP%\t1 >%TEMP%\t2 CMD: DEL %TEMP%\t1 CMD: cmd3 <%TEMP%\t2 >out CMD: DEL %TEMP%\t2 EXAMPLE: 3 The error stream can be piped as well:
CMD: cmd1 |& cmd2 | cmd3
Which is similiar to this sequence:
CMD: cmd1 >&%TEMP%\t1 CMD: cmd2 <%TEMP%\t1 >%TEMP%\t2 CMD: DEL %TEMP%\t1 CMD: cmd3 <%TEMP%\t2 CMD: DEL %TEMP%\t2
Here only the error messages of <CMD>cmd1</CMD> are passed into <CMD>cmd2</CMD>; the error messages of both <CMD>cmd2</CMD> and <CMD>cmd3</CMD> 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 <CMD>BATCH.BAT</CMD>:

    @ECHO OFF
    ECHO 1
    ECHO 2 >out_2
    ECHO 3

which is invoked via:
CMD: BATCH >out_1
When the script <CMD>BATCH</CMD> gets executed, the actual output stream is redirected to the file <CMD>OUT_1</CMD>. 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 <CMD>OUT_2</CMD>. 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 <CMD>OUT_1</CMD> again.

## Wildcards

DOS accepts certain placeholders instead of files, so you can specify one or more files with the same wildcard pattern. In opposite to other systems each program expands wildcards individually instead of let the shell do this; however, the shell must epxand wildcards for its internal commands.

FreeCOM supports the standard DOS wildcards as supported by the DOS kernel itself:

Wildcard | Meaning
--- | ---
<CMD>*</CMD> | Any remaining body, except a dot (<CMD>.</CMD>)
<CMD>?</CMD> | Any character, except the dos (<CMD>.</CMD>); acts as <CMD>*</CMD>, if the last character

Wildcards are allowed in the last portion of a qualified path, that means behind the last backslash (<CMD>\</CMD>) or colon (<CMD>:</CMD>).
Wildcards match either before or behind the dot delimiting the filename and its extension.
Whether or not directories or volume lables or hidden and system files do match a pattern depends on the command expanding it.
Letters match case-insensitively.

Examples:

Pattern | Meaning
--- | ---
<CMD>*.*</CMD> | Any file in the current directory
<CMD>c:*.*</CMD> | Any file in the current working directory of drive C:
<CMD>*</CMD> | Any file without an extension. Some commands, such as DIR, interprete a single <CMD>*</CMD> as <CMD>*.*</CMD>
<CMD>a*.*</CMD> | Any file, which first character is an <CMD>A</CMD>, neither the remainder of the filename nor the extension of the file matters
<CMD>a?.*</CMD> | same as above
<CMD>a???.*</CMD> | same as above
<CMD>a*b.*</CMD> | same as above
<CMD>a?b.*</CMD> | Any file, which first character is an <CMD>A</CMD> and the third one is a <CMD>B</CMD>; the remaining characters nor the extension matter
<CMD>file?.txt</CMD> | All files, which first four characters are <CMD>FILE</CMD> and which extension is equal to <CMD>TXT</CMD>
<CMD>\scripts\*.pl</CMD> | Any perl file in the directory <CMD>\SCRIPTS</CMD> located in the root directory of the currently selected drive

Warning: There are common mistakes about wildcards, as DOS has less functional wildcards than other systems, in particular:

- <CMD>a*bc.*txt</CMD>: Any character right of an asterisk <CMD>*</CMD> up to the dot <CMD>.</CMD> or the end of the filename is ignored; this pattern is equal to: <CMD>a*.*</CMD>.
- <CMD>a?.?</CMD>: A question mark <CMD>?</CMD> as the last character of either the filename or file extension has the same effect as an asterisk <CMD>*</CMD> and does not mean exactly one any character, in particular no character must be present; this pattern is equal to <CMD>a*.*</CMD>.

## Batch Scripts

The shell lets to automate simple tasks by writing batch scripts. These are plain text files with one command is written at one line. Any command, both internal and external ones, can be used in batch scripts, along with redirections, pipes, environment variable substitions a.s.o. The script is performed line-by-line.

By default, before executing a line, it is displayed onto the screen, in order to prevent this, one can turn off this feature with the ECHO command or prefix each line with the Ad sign (<CMD>@</CMD>), e.g.:
CMD: ECHO This line is displayed CMD: @ECHO This line is NOT displayed
Commonly batch scripts start with the line:
CMD: @ECHO OFF
in order to turn off to echo each line furtherly in the script processing and to suppress to echo the line itself, too.

Lines starting with a colon (<CMD>:</CMD>) label this particular script line, in order to be jumped to with the GOTO command, e.g.:
CMD: @ECHO OFF CMD: IF "%1"=="" GOTO useage CMD: ECHO argument1=%1 CMD: ECHO argument2=%2 CMD: ECHO argument3=%3 CMD: GOTO ende CMD: :useage CMD: ECHO Useage: %0 {arguments}... CMD: :ende

- If the script is invoked with no argument, line 2 performs the GOTO command and, thus, skips the lines 3 through 7 and proceeds with line 8.
- Otherwise the three ECHO commands are invoked and the GOTO command of line 6 skips the ECHO'ing of the error message in line 8 and proceeds in line 9.

If the shell hits a line starting with a colon, it is silently skipped; not even redirections are evaluated in opposite to the REM command.

When the shell reaches the end of the file, the batch processing terminates. The errorlevel of the last spawned external command remains unchanged. Because the shell closes the batch script and re-opens it each time a command, for both internal and external ones, is invoked, one can savely replace floppy disks during a batch processing, e.g.:
CMD: @ECHO OFF CMD: ECHO Copying disk1 CMD: COPY files\*.* C:%1 CMD: :disk2 CMD: PAUSE Insert disk #2, then hit ENTER CMD: IF NOT EXIST disk2 GOTO disk2 CMD: ECHO Copying disk2 CMD: COPY files\*.* C:%1 CMD: :disk3 CMD: PAUSE Insert disk #3, then hit ENTER CMD: IF NOT EXIST disk2 GOTO disk3 CMD: ECHO Copying disk3 CMD: COPY files\*.* C:%1 CMD: ECHO Copying done.

When a batch file is invoked within another batch file, the previous ones does not proceed once the called one terminates, regardless of the nesting level; this is called chaining, one chains to another program and does not intend to come back. To have a batch script behave like an external program in this regard, it must be invoke via the CALL command, e.g.:
CMD: @ECHO OFF CMD: ECHO %0 - line 2 CMD: CALL batch2 CMD: ECHO %0 - line 4
and <CMD>BATCH2.BAT</CMD>:
CMD: ECHO %0 - line 1