random-mirrors
/
MS-DOS
mirror of https://github.com/microsoft/MS-DOS.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
MS-DOS/v2.0/bin/UTILITY.DOC

813 lines
27 KiB
Plaintext
Raw Normal View History

MS-DOS v2.0 Release
1983-08-13 01:53:34 +01:00
MS-DOS 2.0
Utility Extensions
The following notation is used below:
[item] item is optional.
item* item is repeated 0 or more times.
item+ item is repeated 1 or more times.
{item1 | item2}
item1 is present or item 2 is present but
not both.
<object> indicates a syntactic variable.
COMMAND invokation
COMMAND [[<drive>:]<path>] [<cttydev>] [-D] [-P] [-C <string>]
-P If present COMMAND will be permanent, otherwise
this is a transient command.
-D If present COMMAND will not prompt for DATE and
TIME when it comes up.
d: Specifies device where command will look for
COMMAND.COM current default drive if absent.
<Path> Specifies a directory on device d: root
directory if absent.
<cttydev> Name of the CTTY device. /DEV/CON if absent
and command is permanent. The /DEV/ may be left
off if AVAILDEV is TRUE (see sysinit doc).
-C <string> If present -C must be the last switch.
This causes COMMAND to try to execute the string
as if the user had typed it at the standard input.
COMMAND executes this single command string and
then exits. If the -P switch is present it is
ignored (can't have a single command, permanent
COMMAND). NOTE: ALL of the text on the command
line after the -C is just passed on. It is not
processed for more arguments, this is why -C must
be last.
COMMAND extensions
IF <condition> <command>
where <condition> is one of the following:
ERRORLEVEL <number>
true if and only if the previous program EXECed by
COMMAND had an exit code of <number> or higher.
<string1> == <string2>
true if and only if <string1> and <string2> are
identical after parameter substitution. Strings
may not have embedded delimiters.
EXIST <filename>
true if and only if <filename> exists.
NOT <condition>
true if and only if <condition> is false.
The IF statement allows conditional execution of commands.
When the <condition> is true, then the <command> is
executed otherwise, the <command> is skipped.
Examples:
IF not exist /tmp/foo ECHO Can't find file /tmp/foo
IF $1x == x ECHO Need at least one parameter
IF NOT ERRORLEVEL 3 LINK $1,,;
FOR %%<c> IN <set> DO <command>
<c> can be any character but 0,1,2,3,..,9 (so there is no
confusion with the %0 - %9 batch parameters).
<set> is ( <item>* )
The %%<c> variable is sequentially set to each member of
<set> and then <command> is evaluated. If a member of
<set> is an expression involving * and/or ?, then the
variable is set to each matching pattern from disk. In
this case only one such <item> may be in the set, any
<item>s after the first are ignored.
Example:
FOR %%f IN ( *.ASM ) DO MASM %%f;
for %%f in (FOO BAR BLECH) do REM %%f to you
NOTE: The '%%' is needed so that after Batch parameter
(%0 - %9) processing is done, there is one '%' left.
If only '%f' were there, the batch parameter processor
would see the '%' then look at 'f', decide that '%f'
was an error (bad parameter reference) and throw out
the '%f' so that FOR would never see it. If the FOR
is NOT in a batch file, then only ONE '%' should be
used.
SHIFT
Currently, command files are limited to handling 10
parameters: %0 through %9. To allow access to more than
these, the command SHIFT will perform a 'pop' of the
command line parameters:
if %0 = "foo"
%1 = "bar"
%2 = "blech"
%3...%9 are empty
then a SHIFT will result in the following:
%0 = "bar"
%1 = "blech"
%2...%9 are empty
If there are more than 10 parameters given on a command
line, then the those that appear after the 10th (%9) will
be shifted one at a time into %9 by successive shifts.
:<label>
This is essentially a no-op. It defines a label in the
batch file for a subsequent GOTO. It may also be used to
put comment lines in batch files since all lines that
start with ':' are ignored.
GOTO <label>
Causes commands to be taken from the batch file beginning
with the line after the <label> definition. If no label
has been defined, the current batch file will terminate.
Example:
:foo
REM looping...
GOTO foo
will produce a infinite sequence of messages:
'REM looping...'
NOTE: Labels are case insensitive, :FOO == :foo == :Foo
ECHO [{ON | OFF | <message>}]
Normally, commands in a BATCH file are echoed onto the
standard output as they are seen by COMMAND. ECHO OFF
turns off this feature. ECHO ON turns echoing back on.
If ON or OFF is not specified and there is text following
the command, that text (a message) is echoed to standard
output. If there are no arguments at all, the current
setting of echo (on or off) is echoed to the standard
output in the form:
ECHO is xxx
Where xxx is "on" or "off".
Redirection of standard input/standard output.
Programs that read from the keyboard and write to the
screen are said to be doing I/O to the standard input and
standard output. Using any of the following will result
in I/O to these standard devices:
Writing to default handles 1 / read from default
handle 0.
Doing byte I/O using system calls 1, 2, 6-12.
These standard devices may be redirected to/from files by
the following in command line arguments:
> <filename>
causes <filename> to be created (or truncated to
zero length) and then assigns standard output to
that file. All output from the command will be
placed in the file.
< <filename>
causes standard input to be assigned to
<filename>. All input to the command will come
from this file. If end-of-file is reached, then
system calls 1, 2, 6-12 will return ^Z , while
reading from handle 0 will return zero characters.
>> <filename>
causes <filename> to be opened (created if
necessary) and positions the write pointer at the
end of the file so that all output will be
appended to the file.
Note that the above will not appear in the command line
that the program being invoked sees.
Examples:
DIR *.ASM > FOO.LST
Sends the output of the dir command to the file
FOO.LST.
FOR %0 IN (*.ASM) DO MASM %0; >>ERRS.LST
Sends all error output from assembling every .ASM file
into the file ERRS.LST.
Piping of standard I/O
It is often useful for the output of one program to be
sent as input to another program. A typical case is a
program that produces columnar output that must later be
sorted.
The pipe feature allows this to occur naturally is the
programs do all of their I/O to the standard devices.
For example, if we had a program SORT that read all of
it's standard input, sorted it and then wrote it to the
standard output, then we could get a sorted directory
listing as follows:
DIR | SORT
The | would cause all standard output generated by the
left-hand command to be sent to the standard input of the
right-hand command.
If we wanted the sorted directory to be sent to a file, we
type:
DIR | SORT >FILE
and away it goes.
The piping feature is implemented as sequential execution
of the procedures with redirection to and from temporary
files. In the example above, the following would be an
exact equivalent:
DIR >/tmp/std1
SORT </tmp/std1 >FILE
The pipe is not a real pipe but rather a quasi-pipe
that uses temporary files to hold the input and output as
it sequentially executes the elements of the pipe. These
files are created in the current directory, of the current
drive and have the form %PIPEx%.$$$, where x will be 1 or
2. This means that any program that runs in the pipe must
be sure to restore the current directory and drive if it
has changed them, otherwise the pipe files will be lost.
VER
Prints DOS version number.
VOL [<drive>:]
Prints the volume ID of the disk in drive d:. No d: does
default drive.
CHDIR [{<drive>: | <path>}]
Change directory, or print current. directory.If no
argument is given, the current directory on the default
drive is printed. If d: alone is given, the durrent
directory of drive d is printed. Otherwise the current
directory is set to path.
NOTE:"CD" is accepted as an abbreviation.
MKDIR <path> - Make a directory.
"MD" is accepted as an abbreviation.
RMDIR <path> - Remove a directory.
"RD" is accepted as an abbreviation.
The directory must be empty except for
'.' and '..'.
<path> - A standard XENIX style path with the optional
addition of a drive spec:
A:/FOO/BAR Full path
/FOO/BAR Full path, current drive
FOO/BAR Current dir relative
A:FOO/BAR " " "
VERIFY [{ON | OFF}]
Select/deselect verify after write mode. This supliments
the V switch to the COPY command. Once turned ON, it
stays on until some program changes it (via the set verify
system call) or the VERIFY OFF command is given. If no
argument is given, the current setting of VERIFY is
printed to the standard output in the form:
VERIFY is xxx
Where xxx is "on" or "off".
PATH [<path>{;<path>}*]
Set command search paths. This allows users to set
directories that should be searched for external commands
after a search of the current directory is made. The
default value is /bin. In addition there are two special
cases: PATH all by itself with no arguments will print
the current path. Path with the single argument ';' (ie.
"PATH ;") will set the NUL path (no directories other than
the current one searched). If no argument is given, the
current value of PATH is printed to the standard output in
the form:
PATH=text of path
or
No path
NOTE: On IBM systems, the default value of path is No
path.
EXIT
For COMMANDs run without the P switch, this causes COMMAND
to return. For a normal COMMAND it causes a return to
itself.
BREAK [{ON | OFF}]
Like in CONFIG.SYS, "BREAK ON" turns on the Control C
check in the DOS function dispatcher. "BREAK OFF" turns
it off. If no argument is given the setting of BREAK is
printed to the standard output in the form:
BREAK is xxx
Where xxx is "on" or "off".
PROMPT [<prompt-text>]
Set the system prompt. MS-DOS prompts are now user
settable, all of the text on the command line is taken to
be the new prompt. If no text is present the prompt is
set to the default prompt. There are meta strings for
various special prompts. These are of the form '$c' where
c is one of the following:
$ - The '$' character.
t - The time.
d - The date.
p - The current directory of the default drive.
v - The version number.
n - The default drive.
g - The '>' character.
l - The '<' character.
b - The '|' character.
s - The ' ' character.
e - The ESC character.
_ - A CR LF sequence.
EXAMPLE:
PROMPT $n:
Would set the normal MS-DOS prompt.
PROMPT $n>
Would det the normal PC-DOS prompt.
PROMPT Time = $t$_Date = $d
Would set a two line prompt which printed
Time = (current time)
Date = (current date)
NOTE: For '$c' sequences, lower case = upper case, and
any character not on the above list is mapped to
nothing.
SET (ENVNAME)=(ENVTEXT)
Set environment strings. This command inserts strings in
COMMAND's environment. For instance:
SET PROMPT=$n>
Duplicates the function of the PROMPT command.
SET PATH=p1;p2
Duplicates the function of the PATH command.
SET foo=bar
Puts the string FOO=bar into the environment (note the
case mapping of (ENVNAME)).
NOTE: Environments are very flexible, almost anything can
be put into the environment with the SET command; the
only requirement is that a single '=' be present in
the string.
CLS
Clear screen, causes the ANSI escape sequence ESC[2J to be
sent to standard output.
CTTY /DEV/dev - Change console TTY. For instance:
CTTY /DEV/AUX
Would move all command I/O to the AUX port.
CTTY /DEV/CON
Would move it back to the normal device. The
/dev/ prefix may be left off if AVAILDEV is
TRUE (see configuration-file doc).
COMMAND internal commands take path arguments.
DIR <path>
COPY <path> <path>
DEL(ERASE) <path>
If the path is a dir, all files in that dir
are deleted.
NOTE: The "Are you sure (Y/N)" prompt for DEL and
ERASE now uses buffered standard input, so
users must type a return after their answer.
This gives them the chance to correct if they
type 'y' by mistake.
TYPE <path> (must specify a file)
FILCOM - compare two files
The FILCOM program compares two files and produces a log
of differences between them. The comparison may be made
in two fashions; either on a line-by-line basis, or on a
byte-by-byte basis.
The line-by-line compare will isolate blocks of lines that
are different between the two files and will print the
blocks from each file. The line-by-line compare is the
default when neither of the two files being compared has
the extension .EXE, .COM, or .OBJ.
The byte-by-byte compare will display exactly which bytes
are different between the two files. If either file being
compared has extension .EXE, .COM, or .OBJ then the files
will be compared in byte-by-byte mode.
RECOVER - recover files from a trashed disk.
If a sector on a disk goes bad, you can recover either the
file that contained that sector (without the sector) or
the entire disk (if the bad sector was in the directory).
To recover a particular file:
RECOVER <file-to-recover>
This will cause the file to be read sector by sector and
to be have the bad sector skipped. Note that this implies
that the allocation unit containing the bad sector will be
read as much as possible. When such a bad sector is
found, its containing allocation unit is marked as bad,
thus preventing future allocations of that bad sector.
To recover a particular disk:
RECOVER <drive-letter>:
This will cause a scan to be made of the drive's FAT for
chains of allocation units (files). A new root directory
is then written that has entries of the form FILEnnnn.
Each FILEnnnn will point to the head of one of the
allocation unit chains.
If there are more chains than directory entries in the
root, RECOVER prints a message and leaves the un-RECOVERED
chains in the FAT so that RECOVER can be run again once
some room has been made in the ROOT.
DEBUG ON MS-DOS 2.0
When 2.0 DEBUG is invoked it sets up a program header
atoffset 0 in its program work area. On previous versions it
was OK to overwrite this header with impunity: this is true
of the default header set up if no <filespec> is given to
DEBUG. If DEBUGging a .COM or .EXE file, however, you must be
careful not to tamper with the header of the program below
address 5CH, to do this will probably result in a crash. It
is also important that an attempt is not made to "restart" a
program once the "program terminated normally" message is
given. The program must be reloaded with the N and L commands
in order for it to run properly.
NEW FEATURES
The A (Assemble) Command
FORMAT: A [<address>]
PURPOSE: To assemble 8086/8087/8088 mnemonics directly into
memory.
o If a syntax error is encountered, DEBUG responds with
^ Error
and redisplays the current assembly address.
o All numeric values are hexadecimal and may be entered
as 1-4 characters.
o Prefix mnemonics must be entered in front of the opcode
to which they refer. They may also be entered on a
separate line.
o The segment override mnemonics are CS:, DS:, ES:, and
SS:
o String manipulation mnemonics must explictly state the
string size. For example, the MOVSW must be used to
move word strings and MOVSB must be used to move byte
strings.
o The mnemonic for the far return is RETF.
o The assembler will automatically assemble short, near
or far jumps and calls depending on byte displacement
to the destination address. These may be overridden
with the NEAR or FAR prefix. For example:
0100:0500 JMP 502 ; a 2 byte short jump
0100:0502 JMP NEAR 505 ; a 3 byte near jump
0100:0505 JMP FAR 50A ; a 5 byte far jump
The NEAR prefix may be abbreviated to NE but the FAR
prefix cannot be abbreviated.
o DEBUG cannot tell whether some operands refer to a word
memory location or a byte memroy location. In this case
the data type must be explicity stated with the prefix
"WORD PTR" or "BYTE PTR". DEBUG will also except the
abbreviations "WO" and "BY". For example:
NEG BYTE PTR [128]
DEC WO [SI]
o DEBUG also cannot tell whether an operand refers to a
memory location or to an immediate operand. DEBUG uses
the common convention that operands enclosed in square
brackets refer to memory. For example:
MOV AX,21 ;Load AX with 21H
MOV AX,[21] ;Load AX with the contents
;of memory location 21H
o Two popular pseudo-instructions have also been included.
The DB opcode will assemble byte values directly into
memory. The DW opcode will assemble word values directly
into memory. For example:
DB 1,2,3,4,"THIS IS AN EXAMPLE"
DB 'THIS IS A QUOTE: "'
DB "THIS IS A QUOTE: '"
DW 1000,2000,3000,"BACH"
o All forms of the register indirect commands are supported.
For example:
ADD BX,34[BP+2].[SI-1]
POP [BP+DI]
PUSH [SI]
o All opcode synonyms are supported, For example:
LOOPZ 100
LOOPE 100
JA 200
JNBE 200
o For 8087 opcodes the WAIT or FWAIT prefix must be
explictly specified. For example:
FWAIT FADD ST,ST(3) ; This lines will assemble
; a FWAIT prefix
FLD TBYTE PTR [BX] ; This line will not
FORMAT enhancements
FORMAT will now install volume id's during the format
process. DIR and CHKDSK will display these volume id's.
User programs can read the volume id on a particular drive
by doing a 'search next' with the volume id attribute. It
is impossible, using normal DOS calls, to delete a volume
id or to create another one. The only way to create a
volume id is to reformat the disk.
NOTE: On IBM systems the V switch must be given to FORMAT
to have it do Volume IDs.
CHKDSK FOR MS-DOS 2.0
MS-DOS 2.0 has a tree structured directory scheme which
did not exist on previous versions of MS-DOS. As a result
CHKDSK is a much more complex program than in previous
versions since it must perform a tree traversal to find all of
the files on a given disk. It employes a depth first
traversal in order to accomplish this.
Previous versions of CHKDSK automatically "fixed"
disks (regardless of whether it was appropriate). CHKDSK 2.00
run normally will not alter the disk in any way, it simply
reports on any inconsistencies found. To actually "fix" a
disk CHKDSK must be run with the F switch (Fix). This allows
you to perhaps take some alternate (to CHKDSK repairs) action
before letting CHKDSK loose on your disk.
CHKDSK 2.00 will report on non-contiguous allocation units
(extents) for specified files. This is handy for gaging how
"fragmented" a disk volume has become. This is done by simply
giving a filespec:
CHKDSK B:*.*
This would report extents for all files in the current
directory for drive B after doing a normal consistency check
on drive B. Files which have many extents can be copied and
renamed to restore them to a contiguous state, thus improving
I/O performance to the files.
Previous versions of CHKDSK would simply free
allocation units which were marked as used, but were not
actually part of any file. CHKDSK 2.00 will recover these
"orphan" allocation units if specified. If orphan allocation
units are found, CHKDSK prompts for free or recover. Free
just frees the orphans as previous versions did, recover will
employ allocation chain analysis to create "orphan files" in
the root directory of the disk. These files will have the
form "%ORPHAN%.l$$" where l will take on some ASCII value
greater than '@'. These files may then be inspected to see if
valuable data was contained in them. If there is not enough
room to make all of the "orphan" files, CHKDSK leaves the
unrecovered chains in the FAT so that CHKDSK can be run again
(once some entries in the ROOT have been deleted). NOTE:
Making ORPHAN files is a SLOW process.
Verbose mode. CHKDSK 2.00 may be run with the V switch
which causes a trace of the files and directories being
processed to be printed as CHKDSK runs.
FILTERS FOR MS-DOS 2.0
A filter is a utility that reads from standard input,
modifies the information in some way, then writes the result
to standard output. In this way the data is said to have been
"filtered" by the program. Since different filters can be
piped together in many different ways a few filters can take
the place of a large number of specific purpose programs. The
following describes the filters that are provided with MS-DOS
2.0:
CIPHER <key word>
Cipher reads a program from standard input, encrypts it
using the key word provided by the user, then writes the
result to standard output. To decrypt the file simply run
CIPHER again using the same keyword. For example:
A>CIPHER MYSTERY <NSA.CIA >SECRET.FIL
This command line will read file NSA.CIA, encrypt it using
the key word "MYSTERY", then write the result to file
SECRET.FIL To view the original file the following command
line could be used:
A>CIPHER MYSTERY <SECRET.FIL
This will read file SECRET.FIL, decrypt the file using the
key word "MYSTERY", then write the result to standard output,
which in this case is the console.
FGREP
This filter takes as arguments a string and optionally a
series of file names. It will send to standard output all
lines from the files specified in the command line that
contain the string.
If no files are specified FGREP will take the input from
standard in. The format for the command line invocation of
FGREP is:
FGREP [<option>] <string> <filename>*
The options available are:
/v Will cause FGREP to output all lines NOT
containing the specified string.
/c Will cause FGREP to only print the count of
lines matched in each of the files.
/n Each line matched is preceded by its relative
line number in the file.
The string argument should be enclosed in double quotes.
Two double quotes in succession are taken as a single double
quote. So,
A>FGREP "Fool""s Paradise" book1.txt book2.txt bible
will output all lines from the book1.txt, book2.txt and bible
(in that order that contain the string: Fool"s Paradise .
And,
A>dir b: | fgrep /v "DAT"
will output all names of the files in disk b: which do not
contain the string DAT .
MORE
The filter MORE reads from standard input, sends one
screen full of information to standard output and then pauses
with message:
-- More --
Pressing the RETURN key will cause another screen full of
information to be written to standard output. This process
continues until all the input data is read.
SORT [/R] [/+n]
Sort reads from standard input, sorts the data, the writes
the information to standard output. The sort is done using
the ASCII collating sequence. There are switches which allow
the user to select various options:
R - Reverse the sort, that is make "Z" come before "A"
+n - Sort starting with column "n" where n is some integer.
The default is start the comparisons with column 1,
this switch allows the user to start in any column.
example:
A>SORT /R <UNSORT.TXT >SORT.TXT
This command line will read the file UNSORT.TXT, do a reverse
sort, then write the output to file SORT.TXT
A>DIR | SORT /+14
This command line will cause the output of the directory
command to be piped to the sort filter, the sort filter will
sort starting with column 14 (This is the column the file size
starts), then send the output to the console. Thus a
directory sorted by file size will be the result. To get real
fancy:
A>DIR | SORT /+14 | MORE
will do the same thing except that MORE will give you a chance
to read the directory before it scrolls off the screen.