The World of Computer Software/World_Of_Computer_Software-02-387-Vol-3of3.iso/t/tsrutls.zip/TSR.DOC

Text File | 1993-03-04 | 23KB | 528 lines

                       TSR Utilities Version 2.9
                             Kim Kokkonen
                          TurboPower Software

Introduction
------------
The TSR Utilities are a collection of programs useful for managing DOS
memory, particularly for managing memory-resident programs, also known as
TSRs. TSR stands for "Terminate and Stay Resident." The most popular use
of The TSR Utilities is for removing TSRs from memory without rebooting
the PC. There are many other uses, however.

The TSR Utilities have grown to include 8 programs. Here's a quick
overview of each one:

  MARK     marks a position in memory above which TSRs can be released.
  RELEASE  removes TSRs from memory.
  FMARK    performs the same function as MARK but uses less memory.
  WATCH    a TSR itself, it keeps track of other TSRs.
  DISABLE  disables or reactivates TSRs, leaving them in memory.
  RAMFREE  shows how much RAM memory is available.
  MAPMEM   shows what memory resident programs are loaded.
  EATMEM   uses up memory for controlled program testing.

Be sure to read the documentation before using these programs. All of the
programs are command line driven, and unexpected events may occur if you
just start typing the program names at the DOS command line.

NOTE: Due to limited disk space, this version of The TSR Utilities does
not include three programs normally included. Two of them, MARKNET and
RELNET, are designed solely for use on Novell Network systems. The other,
DEVICE, is a program to display information about installed device
drivers. See the end of this file for information on obtaining the version
The TSR Utilities that contains these programs.

System Requirements
-------------------
The TSR Utilities will run on any IBM-compatible computer. You need DOS
2.0 or a later version. Memory requirements vary according to the TSR
programs you normally use. Any monitor is acceptable.

Installation
------------
For easiest use on hard disks, copy the program files to a directory named
in the PATH statement in your AUTOEXEC.BAT file. For more information on
the PATH command, see your DOS Manual.


MARK, FMARK, and RELEASE
------------------------
MARK.COM and RELEASE.EXE are used to remove TSRs from memory, without
requiring a system reboot. In their simplest form, MARK and RELEASE are
used as follows:

1. Run MARK before installing your TSR(s). This marks the current position
in memory and stores information that RELEASE will later need to restore
the system. A common place to call MARK is in your AUTOEXEC.BAT file.

2. Install whatever TSRs you want, using the normal method for each TSR.

3. To remove those TSRs from memory, run RELEASE. This will release all
of the memory above (and including) the last MARK, and will restore the
system to the state at the time the MARK was made.

There are a number of variations of this simple method. First, MARKs can
be stacked in memory, as shown in the following hypothetical batch file.
Where you see TSR(n), substitute the name of the program you're
installing.

    MARK
    TSR1
    MARK
    TSR2
    MARK
    TSR3

Each call to RELEASE releases memory above and including the last MARK. In
this example, the first call to RELEASE would remove TSR3 and the last
MARK from memory, the second call would remove TSR2 and its MARK, and so
on.

MARK and RELEASE can be called using a command line parameter. The
parameter specifies a "mark name" and allows releasing TSRs to a specific
point in memory. Consider the following example:

    MARK TSR1
    TSR1
    MARK TSR2
    TSR2
    MARK TSR3
    TSR3

This loads the three TSRs just as in the previous example. However, if
RELEASE were called like this

    RELEASE TSR2

then both TSR2 and TSR3 would be removed from memory. Note that the use of
such a name does not allow just a single layer of TSRs to be removed
(just TSR2, for example). RELEASE always removes all TSRs including and
beyond the one named.

A mark name is any string up to 126 characters long. The name may not
include white space (blanks or tabs).

When named marks are used, calling RELEASE without specifying a mark name
will still remove the last TSR from memory. Assuming that TSR1, TSR2, and
TSR3 are still in memory, typing just RELEASE would remove TSR3 and the
last mark.

You can change this behavior by using "protected marks," which can be
released only by explicitly specifying their names. A protected mark is
placed by giving it a name that starts with an exclamation point, '!'.
Consider the following:

    MARK TSR1
    TSR1
    MARK TSR2
    TSR2
    MARK !TSR3
    TSR3

Here !TSR3 specifies a protected mark. RELEASE alone would produce an
error message "No matching marker found, or protected marker encountered."
The same error would occur after entering the command, RELEASE TSR2. When
this error occurs, RELEASE does not remove any TSRs from memory.

The only way to remove TSR3 in this case is by entering

    RELEASE !TSR3

Each time a MARK is placed in memory, it consumes about 1600 bytes of RAM
space, which is used to store a copy of the system interrupt vector table
and other information with which RELEASE can later restore the system.
Although 1600 bytes isn't very much, we can reduce this memory usage by
storing the information in a disk file rather than in memory. FMARK.COM is
a variation on MARK that does just that. You can call FMARK at any time
that you would call MARK. FMARK uses only about 150 bytes of memory.

All calls to FMARK must include a command line parameter to specify the
name of the file:

    FMARK [d:][directory]filename

You should generally specify a complete pathname for the mark file. When
you later call RELEASE, you must give it the identical pathname,
regardless of what the current directory happens to be at the time. For
example, if you specified the following file mark:

    FMARK C:\TEST\TEST.MRK

then the following calls to RELEASE would generate an error:

    RELEASE TEST.MRK
    RELEASE C:TEST.MRK

even if the current directory on drive C: was \TEST. The only way to call
RELEASE is with

    RELEASE C:\TEST\TEST.MRK

RELEASE can use either type of mark. Note that RELEASE treats marks placed
with FMARK just like protected marks. That is, they can be released only
by explicitly naming them.

Consider the following example:

    MARK
    TSR1
    FMARK C:\MARKS\TSR2.MRK
    TSR2

Typing just RELEASE in this situation generates the warning message "No
matching marker found, or protected marker encountered," because the file
mark is treated like a protected mark.

TSR2 can be removed from memory by entering

    RELEASE C:\MARKS\TSR2.MRK

RELEASE deletes the mark file when it has finished.

RELEASE has several command line options to modify its behavior. The
following table lists the options, which must start with a slash, '/', or
a hyphen, '-'.

    /E         do NOT access EMS memory.
    /K         release memory, but keep the mark in place.
    /S chars   insert string (<16 chars) into keyboard buffer on exit.
    /?         display a help screen.

None of the options is required for normal use of RELEASE.

/E is made available for systems running early, buggy EMS (expanded
memory) drivers that don't correctly implement all of the EMS 3.2 system
calls. Don't use it unless you have an EMS-related problem during or after
running RELEASE.

/K is useful when you will be releasing and reloading a TSR repeatedly.
With it, you avoid the need to replace the mark each time the TSR is
released. Using /K in combination with a file mark also prevents RELEASE
from deleting the mark file.

/S followed by at least one space and then a short string (15 characters
or fewer) tells RELEASE to insert this string into the keyboard buffer
just before exiting. RELEASE automatically adds a carriage return to the
end of the string.

To explain why the /S option is important, we must digress a moment. Let's
assume that you normally keep SideKick loaded, but that you must unload it
in order to have enough memory free to run Lotus 1-2-3. It would seem
reasonable to write a little batch file like this:

   RELEASE SK
   LOTUS
   MARK SK
   SK

which would remove the previously loaded SideKick from memory, run Lotus,
and then load SideKick again. Unfortunately, this won't work!

The reason is complicated to explain. It must suffice here to say that DOS
batch files trap memory, and the memory freed by a call to RELEASE does
not truly become available until the current batch file ends.

Now perhaps the need for the /S option becomes clear. We can split the
previous batch file into two:

  batch1:
    RELEASE SK /S BATCH2

  batch2:
    LOTUS
    MARK SK
    SK

The first batch file releases the memory and stuffs the characters
'BATCH2<Enter>' into the keyboard buffer. When the batch file ends, the
released memory becomes available. DOS automatically reads the keystrokes
waiting in the buffer and starts up the second batch file, which runs
Lotus and later reloads SideKick.

To keep things simple, the /S option pokes the specified keystrokes
directly into the system keyboard buffer. As a result, the number of
keystrokes is limited to 15 (not counting the <Enter> key, which RELEASE
adds automatically). This always allows enough keys to start another batch
file, however, and the new batch file can take over from there.

RELEASE detects when it is releasing memory within a batch file. It writes
a warning message to that effect, but continues processing anyway under
the assumption that the batch file is about to end. You can ignore the
warning if you've already taken account of DOS's memory management
behavior within batch files.

MARK and RELEASE are capable of removing many, but not all, TSRs from
memory. The TSRs that cannot be released fall into two categories: those
that cannot be released without specific internal knowledge of the TSR,
and those that can be released by storing additional general information
about the system.

The most common examples of TSRs that can't be released without internal
knowledge are those that cooperate with other TSRs in memory. Examples
include Microsoft's MOUSE.COM driver and its associated MENU program, and
the program CED with its "user-installed commands" such as KEYIN, HS, RAW,
and others. These programs can be released, but only if all the
cooperating partners are released at the same time. CED is well-behaved in
that it provides a built-in command (KILL) to release its partners.
MOUSE.COM is not so flexible, though.

Other TSRs modify well-defined areas of DOS memory that MARK and FMARK
simply don't record. Examples of such TSRs include the Novell NetWare
workstation shell and certain DOS utilities like MODE and SHARE.

WARNING: you should not use RELEASE to try to release most disk caching
programs. If you do so, part of the information that should be stored on
disk will never make it, and you may end up with a corrupted disk as a
result. If you know that the disk cache uses a "write-through" algorithm
(which guarantees that all writes immediately go to disk), or if the disk
cache has a "flush the cache" command, then it may be safe to release the
cache.

WARNING: you cannot release the DOS 3.3 FASTOPEN or APPEND TSRs. These
TSRs patch internal DOS data areas that cannot be reliably located.


WATCH and DISABLE
-----------------
WATCH.COM is a resident program that keeps track of other memory resident
programs. As a TSR goes resident, WATCH updates a data area in memory that
contains information about what interrupt vectors were taken over. This
information can later be used by MAPMEM and DISABLE to show more details
about interrupts than normally available.

Installation of WATCH.COM is optional. All of the TSR Utilities except
DISABLE can be used whether or not WATCH is installed.

If you want to use it, WATCH.COM should be installed as the first TSR in
your AUTOEXEC.BAT file. WATCH uses about 4000 bytes of memory when it is
installed. Most of this memory holds various information about the TSRs
installed in the system -- it includes two copies of the interrupt vector
table and a data area containing a list of the interrupt vectors taken
over by each TSR. This information is used by DISABLE to deactivate and
reactivate TSRs without removing them from memory.

With DISABLE.EXE, you can disable and re-enable specified memory resident
programs without removing them from memory. Its function is analogous to
that performed by REFEREE from Persoft, although DISABLE has neither a
fancy user interface nor an option to work from within other programs.
DISABLE can allow conflicting TSRs to coexist, and it can let you run
applications whose keystrokes conflict with those of TSRs already loaded.
DISABLE also provides a small bonus in that it can be used to detect the
presence of a particular TSR in memory, thus allowing the design of
semi-intelligent batch files.

In order to use DISABLE, you must install WATCH.COM as the first memory
resident program in your system. WATCH keeps the detailed information
about each memory resident program that DISABLE uses to later control
them.

Like the other TSR Utilities, DISABLE is operated from the command line.
You specify a single TSR by its name (if you are running DOS 3.0 or later)
or by its address as determined from a MAPMEM report (described below). If
you specify an address, immediately precede the address with a dollar sign
"$" and specify the address in hexadecimal.

The name specified for a TSR is the one reported by MAPMEM in the "owner"
column. If the owner column reports "N/A," then you must instead specify
the address from the "PSP" column.

DISABLE accepts the following command line syntax:

  DISABLE TSRname|$PSPaddress [options]

Options can be preceded by either / or -. Valid options are as follows:

     /A     reactivate the specified TSR.
     /C     check for the presence of the specified TSR.
     /?     display a help screen.

If no option is specified, DISABLE will disable the named TSR.

Examples of usage:

  DISABLE SK              disables SideKick
  DISABLE SK /A           re-enables SideKick
  DISABLE SK /C           checks for the presence of SideKick
  DISABLE $2F2E           disables the TSR at address 2F2E (hex)

DISABLE sets the DOS ERRORLEVEL in order to return status information to a
batch file. It uses the following values of errorlevel:

  0       success: TSR is present, was disabled, or was re-enabled.
  1       TSR is present, but no action was required to enable or disable it.
  2       TSR is not present in memory.
  254     invalid command line.
  255     severe error.

WARNING: you cannot use DISABLE to deactivate SideKick Plus, whose
swapping technique is incompatible with DISABLE.


MAPMEM and RAMFREE
---------------------------
These two utilities provide status information about DOS memory usage.
They don't make active changes to the system like RELEASE and DISABLE do.

MAPMEM.EXE displays a map of DOS memory. It shows the resident programs,
how much memory they use, and what interrupt vectors each one controls.
MAPMEM also shows information about expanded and extended memory when
available.

MAPMEM writes to the standard output -- the output can be printed or
stored to a file by using DOS redirection.

Here is an example of MAPMEM output:

 PSP  blks bytes owner    command line        chained vectors
----- ---- ----- -------- ------------------- ------------------------------
0008   1   34240 config
1228   2    3536 command
1315   2    3888 WATCH    TSR WATCHER         16 21 27
140A   2   22128 CED      N/A                 1B 21 64
1973   1     144 N/A      C:\MARK\PS.MRK
197D   2     736 PSKEY    S3                  09 15
19AD   2   68400 PS       /B:0 /E:1 /R:0 /... 01 03 06 0D
2A62   2    1504 MARK     test                00 3F
2AC2   2   10384 EATMEM   10
2D4D   2  469808 free

block   bytes   (Expanded Memory)
-----   ------
    1  1048576
 free  1048576
total  2097152
                (Extended Memory)
total   379240

"PSP" stands for Program Segment Prefix. This is the physical address,
specified in hexadecimal, where the program was loaded. If you're running
DOS 2.x, you'll need to use an address from this column to pass to
DISABLE.

"Blks" is the number of memory blocks DOS is using to manage the program.
This will typically be two: one for the program itself and another for the
environment that stores the program name, the DOS path, and other
environment variables.

"Bytes" is the number of bytes of memory, specified in decimal, allocated
to the program.

The "owner" column shows the name of the program that allocated the block.
An "N/A" in this column means either that the program de-allocated its
environment to reduce memory usage (as shown on the fifth row of the
report) or that the system is running DOS 2.x, where the owner names are
simply not available.

"Command line" shows the command line entered when the TSR was originally
loaded. Some TSRs overwrite their command line with other code or data in
order to save memory space. MAPMEM can usually detect this behavior and
will display "N/A" in the command line column when it does.

The last column will be titled with either "chained vectors" or "hooked
vectors." When WATCH is loaded, "chained" will appear; otherwise, "hooked"
will. The numbers in this column indicate what interrupt vectors the TSR
has grabbed. Without WATCH, MAPMEM must use a heuristic technique to
identify the owner of each vector; don't be surprised if you see some
ridiculous looking vector numbers. With WATCH, MAPMEM should report an
accurate list for each TSR and should show the complete chain of control
for each interrupt.

MAPMEM indicates disabled TSRs by displaying the word "disabled" in the
interrupt vector column of the report.

The expanded memory report shows each allocated block of expanded memory,
as well as the free and total EMS space. When extended memory is
available, MAPMEM shows just the total amount available. The extended
memory report is not highly reliable because of the lack of a standardized
method for allocating extended memory space. Some applications that use
extended memory allocate the space by making it appear that the memory is
no longer in the system.

MAPMEM shows the various types of marks so that you can examine them prior
to releasing them. As shown in the example, MAPMEM reports a call to
MARK with the owner name "MARK," and the mark name (if any) in the command
line area. The result of a call to FMARK or MARKNET will show "N/A" in the
owner column (due to the minimal memory kept by an FMARK), and the name of
the mark file in the command line area.

MAPMEM offers the following command line options:

     /V     verbose report.
     /?     display a help screen.

The verbose report shows each individual memory block rather than just one
for each program. It also adds two new columns of information. "Mcb"
stands for Memory Control Block. This is a physical address, expressed in
hexadecimal, of the DOS data structure used for managing each block of
memory. The MCB address is typically one less than the address of the
program. "Files" reports the number of files kept open by the TSR. In most
cases this will be zero. When it is non-zero, the maximum number of files
opened by the rest of the programs (including the foreground application)
is reduced accordingly.

RAMFREE.COM is a tiny program with a single purpose: to tell you how many
bytes of memory are free for the next application. RAMFREE's advantage
is that you don't need to wait for your hard disk to be analyzed before
you find out how much memory is free. (Please note that, due to
differences in DOS versions, there may be very small discrepancies
between the bytes free reported by MAPMEM, RAMFREE, and DOS's CHKDSK.)

EATMEM
------
EATMEM is a small program that is useful to software developers. It is a
TSR that consumes a specified amount of memory. Developers can use it to
simulate a system with less memory, or to create a buffer zone between an
application and programs preceding it.

The memory used by EATMEM can be freed only by using MARK and RELEASE.
Call EATMEM with a single command line parameter, specifying the (decimal)
number of KILOBYTES to eat up:

  EATMEM KiloBytesToEat

EATMEM will allow you to eat up all available memory, leading to a system
crash when COMMAND.COM cannot be reloaded. Be sure to calculate how much
memory to use before calling EATMEM.


Copyright and License Information
---------------------------------
The TSR Utilities are copyright (c) 1986,1987,1989 by Kim Kokkonen. All
Rights Reserved.

These programs are copyrighted, but license is hereby granted to
distribute them for personal, non-commercial use. You may use them
yourself, give them to your friends or co-workers, or distribute them for
a cost-based fee ($10 or less) as part of a user's group or bulletin board
service. If you wish to distribute these programs as part of a commercial
package, please contact us for a license agreement.

These programs are not shareware: we're not asking for a donation.
However, if you request that we send you a new version, we'll ask for $20
to cover our time and costs. The disk will include the latest version of
the TSR Utilities, including the complete source code.

The first (and only) place that we upload new versions of the TSR
Utilities is on CompuServe, the BPROGA forum, in the latest Turbo Pascal
library, which at this time is LIB 2. The executable programs are stored
in a file called TSRCOM.ARC, and the source code is stored in a file
called TSRSRC.ARC. From CompuServe, the programs fan out to public domain
bulletin boards around the world. Unfortunately, due to the transient
nature of bulletin boards, we cannot recommend where besides CompuServe
you should call to download the latest version.

The TSR Utilities were written by Kim Kokkonen, with thanks to Neil
Rubenking for the original idea behind MARK and RELEASE. Special thanks to
Richard Wilson and Barry Simon at CalTech for the idea that lead to FMARK,
and for much useful correspondence about the TSR Utilities.

You can reach Kim Kokkonen at:

     TurboPower Software
     P.O. Box 66747
     Scotts Valley, CA 95066-0747

     408-438-8608 (voice only, Monday-Friday 9AM-5PM)
     CompuServe: 72457,2131