List of commands and features of FreeCOM:
Requirements: FEATURE_ALIASES
Synopsis
-
ALIAS
-
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:
<> { 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
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.
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
Requirements: CMD_BEEP
Synopsis
BEEP
Issues a beep.
At this time FreeCOM supports audible beeps only.
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.
See also: LOADFIX, LOADHIGH
Optional requirements: FEATURE_KERNEL_SWAP_SHELL
Synopsis
-
CALL program [ «arguments» ]
-
CALL [ /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.
Note: In the future to swap FreeCOM out of memory during the execution
of an external program will be the default behaviour.
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.
See also: CDD, CHDIR, DIR, DIRS, MD, PUSHD, RD
Requirements: CMD_CHDIR
Optional requirements: FEATURE_LAST_DIR
Synopsis
-
CD
-
CD [ drive ':' ] path
-
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.
See also: CD, DIR, MD, PUSHD, RD
Requirements: CMD_CDD
Synopsis
-
CDD
-
CDD [ drive ':' ] path
-
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.
This command is 100% compatible to CD, please see there
See also: ECHO, TYPE
Requirements: CMD_CLS
Synopsis
CLS
Clears the screen and resets the character colours to
white on black.
See also: DEL, REN
Requirements: CMD_COPY
Synopsis
-
COPY [{ option }] source [{ option }] target [{ option }]
Copies the source file into the target file. See also: \REF{wildcards}
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.
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.
See also: TIME
Requirements: CMD_DATE
Synopsis
-
DATE [ /D ]
-
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.
- In variant 1, the date is displayed only.
- 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.
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.
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.
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.
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.
- /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.
- /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.
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!!
Example: 4
DIR /as ..
DIR .. /a/s
DIR /s .. /a
Because DIR processes all options globally and single-character
options may be joined together, all the above examples behave the same way
and recursively display all files beginning from the current directory's
parent directory including all System and Hidden files.
See also: CD, CHDIR, POPD, PUSHD
Requirements: CMD_DIRS
Synopsis
DIRS
Displays all directories stacked with the PUSHD command.
See also: TYPE
Requirements: CMD_ECHO
Synopsis
-
ECHO [ ON | OFF ]
-
ECHO «string»
-
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
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.
This command is 100% compatible to DEL, please see there
Synopsis
EXIT
Terminates the currently running shell, unless FreeCOM had been started with
the /P option. In this case, EXIT works like CANCEL.
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:
Requirements: IMPLICIT
The batch script processing is always enabled.
Options
Compile-time options:
- BATCH_NESTLEVEL_MIN: Minimal supported batch nesting level.
Default: 5
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.
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).
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.
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
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.:
- if exactly one match was found, its name is appened.
- 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.
- 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
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
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
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.
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 words and patterns enclosed in
parenthises; where patterns 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.
Warning #1: Unlike most commands
I/O-redirections are passed forth to the
command instead of to apply them to FOR itself.
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.
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.
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
Requirements: FEATURE_HISTORY
Synopsis
-
HISTORY
-
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.
Synopsis
-
IF [ NOT ] EXIST file «command»
-
IF [ NOT ] ERRORLEVEL number «command»
-
IF [ NOT ] string '==' word «command»
-
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.
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.
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.
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.
Example:
LOADFIX program.exe
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
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.
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.
This command is 100% compatible to MD, please see there
Requirements: CMD_PATH
Synopsis
-
PATH
-
PATH [ '=' ] { path : ';' }
-
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:
- the current directory
- C:\FDOS\BIN
- C:\TOOLS
- D:\OTHERS\BIN
- 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.
Requirements: CMD_PAUSE
Synopsis
-
PAUSE
-
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.
See also: CD, CDD, DIRS, POPD
Requirements: CMD_CDD, CMD_POPD
Synopsis
-
POPD
-
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.
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
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
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.
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
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
See also: RENAME
Requirements: CMD_RENAME
Synopsis
REN source destination
Options
Unless stated otherwise all options of this command do follow the
standard rules for options.
Examples
Example: 1
This command is 100% compatible to REN, please see there
This command is 100% compatible to RD, please see there
Requirements: CMD_SET
Synopsis
-
SET [{ option }]
-
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 sifn):
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.
Requirements: CMD_SHIFT
Synopsis
-
SHIFT
-
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
See also: DATE
Requirements: CMD_TIME
Synopsis
-
TIME [ /T ]
-
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:
- error,
- hour:minute; seconds and hundreds default to zero,
- hour:minute:seconds; hundreds defaults to zero,
- hour:minute:seconds.hundreds;
- 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.
- In variant 1, the time is displayed only.
- 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.
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
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
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
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
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
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.
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.
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.
In DOS an absolute path is constructed out of several components:
- drive,
- directory,
- filename, and
- 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:.
- C:\
The root directory of drive C:.
- .
The current working directory, ergo: C:\FREEDOS\HELP.
- ..
The parent directory, ergo: C:\FREEDOS.
- D:
The current directory of drive D:, ergo: D:\TEMP.
- D:.
The current directory of drive D:, ergo: D:\TEMP.
- D:..
The parent directory of drive D:, ergo: D:\.
- ..\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.
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:
- /+O: The option is enabled.
- /-O: The option is disabled.
- /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.
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.
There are some special internal commands, that are not directly visible
nor accessable. They are hidden because of two main purposes:
- Many of them are of internal nature and should not used by the user.
- 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.