Category : Pascal Source Code
Archive   : TSRTPU.ZIP
Filename : TSRTPU.DOC

WP3$

















TSR.TPU 1.0 (c)

Copyright 1988 by Jack C. Holt

A Turbo Pascal 4.0 Unit for "Terminate and Stay Resident" Programs

6 Feb 1988










































TSR.TPU

T A B L E O F C O N T E N T S


1. Brief Description .................................. 1
2. Specifics on How to Use It ......................... 1
3. Reference Section .................................. 2
4. Acknowledgements ................................... 3
5. Purchasable Benefits ............................... 3
6. Future Enhancements ................................ 4
7. License/Disclaimer ................................. 4





















































1. BRIEF DESCRIPTION

TSR.TPU contains the code and variables necessary to make a Turbo Pascal
4.0 (otherwise known as TP4) program memory resident. I designed it in such a
way as to make it flexible and easy to use. All you have to do is little
more than assign values to a few variables and call a procedure. In case that
sounds trite, read on and see if you think so.

2. SPECIFICS ON HOW TO USE IT

Before we start in on the specifics, let's get some terminology straight.
TSR stands for "Terminate and Stay Resident" in case you hadn't guessed or
didn't already know. "Hot Key" means the key combination which causes the
memory-resident program to start.

Now for the specifics... The TSRDEMO.PAS program shows a good example
of how to use TSR.TPU. Referring to that, I'll discuss in detail what you
need to do right here and now.

A. The first thing you need to do is to use the "$M" (memory) compiler
directive to specify that the heap maximum is less than all available
memory (TP4 assigns 655360 bytes to the heap maximum, which on many
systems is all available memory). In TSRDemo.Pas, I allowed for 4096
bytes (4 k) but you will probably want to experiment with that number in
order to get a happy medium between the amount of memory your program
"hogs" and running out of heap space (which would definitely "hang" your
PC).

You must restrict the size of the heap because if you don't, no other
program will find memory enough to run after you have installed your TSR
program.

B. The next thing you need to do is include the word "TSR" in the "Uses"
list (look at TSRDemo.Pas if that sounds like greek). Oh, and by the way,
you also need to make sure that you put TSR.TPU in a directory where TP4
can find when you compile. But, hopefully you knew that already.

C. Now we come to some pointers on creating the procedure that contains
the program that you want to make memory resident. Be sure to use the
"$F" compiler directive before and after the Procedure declaration to
force TP4 to set up that procedure so it can be called by a far call
(using both a segment value and an offset value) because that is what
TSR.TPU wants to do (never mind why).

You use "$F+" to turn on far calls and "$F-" to turn them off (once
again see TSRDemo for the example).

D. Now we come to the assignment of the variables I mentioned in the
brief description. I will briefly describe each variable here but if you
want more information on them you should look in the Reference Section
below.

You need to assign a four character string to "TSRSign". This is used
to make sure that the program doesn't install itself more than once if
accidentally run the program more than once.









WPWP KWPKWPKWPKWPKWPKWPKWPKWP TSR.TPU KWPKWPKWPKWPKWPKWPKWPKWP WP
You need to assign the address of the procedure which contains the
program you want to install to a pointer variable called "InstalledProc".
You can use the "@" (address of) operator or the Addr function to do that.
You need to assign the scan code of the hot key to "HotScanCode".
"HotScanCode" is a byte variable. For a list of what the scan codes are
see page 571 (table E.2) of the Turbo Pascal 4.0 manual. I apologize for
the fact that table E.2 is titled "Extended Key Codes" and yet I have
referred to them as scan codes. Without getting very specific, the
problem seems to be a conflict in MS-DOS interrupt naming conventions.

Once you've done all of that, You call the procedure named
"Install_TSR" which does all the heavy duty work of leaving the program in
memory and returning you to the DOS prompt and yet allowing you to "pull
up" the memory-resident program at the touch of the hot key you selected.

Right before you call Install_TSR you will probably want to put in
some Writeln statements that tell the user that the program is now
installed but it isn't necessary.

One additional comment on doing the actual compiling and testing of your
program. First of all don't try to make your program memory resident with TSR
until you have thoroughly tested it without TSR and made sure there are no
bugs in it. Trying to debug a program after it is installed in memory is a
ridiculous prospect and will tend to cause your PC to hang on fatal I/O or
Runtime errors.

And last but definitely not least, when running a program which uses
TSR.TPU, don't do it from the middle of the integrated environment. Always,
COMPILE to disk, exit the integrated environment, and run the program from the
DOS prompt.

3. REFERENCE SECTION

Data:

The data in the TSR unit is defined as follows:

Type
TSRSignType : String[4];

VAR
TSRSign : TSRSignType; {default value 'TSR '}
HotScanCode : Byte; {default value 104 (Alt-F1)}
InstalledCode : Pointer; {no default}

The value of "TSRSign" is installed in memory as a "signature" of the
memory-resident program. When a program which uses TSR installs itself, it
searchs memory for the value of TSRSign. If it finds it, the program exits
immediately without leaving the program in memory and displays, "That's
already in memory!" on the screen.

"TSRSignType" is provided to allow future compatibility if I change the
length of TSRSign. It is highly recommended that you use TSRSignType rather
than "String[4]".




WPWP KWPKWPKWPKWPKWPKWPKWPKWPKWP 2 KWPKWPKWPKWPKWPKWPKWPKWPKWP WP






WPWP KWPKWPKWPKWPKWPKWPKWPKWP TSR.TPU KWPKWPKWPKWPKWPKWPKWPKWP WP
"HotScanCode" should contain the value of the scan code of the hot key.
For a list of what the scan codes are see page 571 (table E.2) of the Turbo
Pascal 4.0 manual. I apologize for the fact that table E.2 is titled
"Extended Key Codes" and yet I have referred to them as scan codes. Without
getting very specific, the problem seems to be a conflict in MS-DOS interrupt
naming conventions.

*** NOTE: TSR does not support using normal typewriter keys (i.e., a-z, A-Z,
and the number keys and their shifted versions, unless in combination with
the Alt key) as hot keys.

"InstalledProc" holds the address of the procedure which you want to
become active at the press of the "hot key". You can get that address with
the "@" (address of) operator or the Addr function.

Procedures:

The only procedure in TSR.TPU which you have access to is "Install_TSR".
It is defined as follows:

Procedure Install_TSR;

As you can see, it takes no parameters. It should be called as the last
statement in the main code of the program which uses TSR.

4. ACKNOWLEDGEMENTS

Rather than "reinvent the wheel" much of the content of the TSR Unit was
built on work done by Neil J. Rubenking and Lane Ferris. The breakthrough on
how to go about writing TSR.TPU came when I read Neil J. Rubenking's article
entitled "Turbo Pascal 4.0: Making the Big Move" on page 277 of the January
26, 1988 issue of PC Magazine.

I also gained great insight from Graham Pearson's article called "Coding
Guidelines for Resident Programs" in the 1987 Programmer's Journal.

5. PURCHASABLE BENEFITS

Since I'm into this for supporting my family, I would now like to put
forth something which may entice some of you into sending me some money.

First of all, since TP4 supports separately compilable units, I was able
to make TSR.TPU available WITHOUT making the source code available for free.
While I would prefer that you send me $15.00 if you plan to use TSR.TPU even
without the source code, I am willing to send you the source code on diskette
for a total of $25.00 (you are also purchasing the right to modify the source
code to your hearts content, only please give me some credit when you do so!).
Please send your orders to:

TSR
c/o Jack C. Holt
1109 N. Main
Orem, UT 84601





WPWP KWPKWPKWPKWPKWPKWPKWPKWPKWP 3 KWPKWPKWPKWPKWPKWPKWPKWPKWP WP






WPWP KWPKWPKWPKWPKWPKWPKWPKWP TSR.TPU KWPKWPKWPKWPKWPKWPKWPKWP WP
6. FUTURE ENHANCEMENTS

In the next version, I plan to include the ability to deinstall a TSR
program from within the TSR program.

I also plan to include a window manager since windows are such an
important part of most TSR programs.

I will also take other suggestions for additions if you have them.

7. LICENSE/DISCLAIMER

TSR.TPU is being distributed by means of the shareware concept. That does
NOT mean it is free software. It is copyrighted software. You are allowed to
use it for free while you are trying it out. Thereafter please send your
donations to the address above.

This program is provided AS IS without any warranty, expressed or implied,
including but not limited to fitness for a particular purpose.

-----------------------------------------------------

Turbo Pascal is a registered trademark of Borland International, Inc.



































WPWP KWPKWPKWPKWPKWPKWPKWPKWPKWP 4 KWPKWPKWPKWPKWPKWPKWPKWPKWP WP






WP3$
I N D E X


Acknowledgements 3
Brief Description 1
Compiling 2
Extended Key Codes 2,3
Future Enhancements 4
Heap Maximum 1
Hot Key 1
Hot Keys, Supported 3
HotScanCode 2,3
How to use TSR 1
InstalledProc 2
Install_TSR 2
License/Disclaimer 4
Ordering Information 3
Reference 2
Scan Codes 2,3
Signature 2
TSR 1
TSRSign 1,2
TSRSignType 2
Uses List 1
$F Compiler Directive 1
$M Compiler Directive 1