RECALL, v1.1a
-------------
from TifaWARE




What's New
----------


Version 1.1 was the first public release of RECALL.




Introduction
------------


RECALL is a memory-resident commandline editor and history utility.
If until now you've been using DOS' built-in yet primitive editing keys
you'll be pleasantly surprised. With RECALL you get improved commandline
editing - including cursor movement and deletion by character/word/line -
as well as a 1K LIFO buffer for keeping track of previously entered
commandlines, commandlines which can be recalled with a single keystroke.

Once installed in memory (it takes less than 2.5K) RECALL intercepts
requests for buffered input and processes them itself. Typically, this
type of input is used by DOS to read commands at the familiar "C>" prompt,
although programs like DEBUG and LIST use it too. Ordinary keystrokes are
saved in a buffer while you edit the commandline and then passed along
when you hit just as they would be if RECALL were not active. A
few special keys, however, let you edit what you've just typed or even
recall commands entered earlier. These special keys - described below -
are what make RECALL so useful.




Usage
-----


Running this program is quite simple. Assuming you've put RECALL.COM
where DOS can find it, type "RECALL -?" to display a brief help message
similar to the following:

TifaWARE RECALL, v1.1a, 10/31/90 - commandline editor and history TSR.
Usage: recall [-options]

Options:
-i = install in memory
-l = list commandlines in recall buffer
-r = remove from memory
-? = display this help message

Only one option can be specified at a time.

[If you don't remember anything else from reading the documentation, at
least remember how to display this help message.]

There are two points of interest about RECALL's syntax. First, you
must explicitly request that RECALL be installed in memory using the '-i'
option. The reason for this extra work is that I consider it impolite for
a program to alter a user's environment without permission. Second,
options are mutually exclusive. (Who'd want to specify more than one
option anyway?)

Generally it's easiest to install RECALL from your AUTOEXEC.BAT -
this way you'll have it available at all times. If you install other TSRs
too, note that RECALL does not care where in the TSR chain it lies. Should
you choose not to install RECALL at boot time though, please be aware that
it's generally unwise to install any TSR while "shelled out" to DOS from
some other program.

With RECALL resident chances are you won't even notice its presence -
not, that is, until you need it. You'll enter commandlines just as you did
before, only now RECALL's power, as summarized by the following table, is
just a single keystroke away:


Key Action
--------------- -----------------------------------------
Movement: Move cursor 1 character to left
Move cursor 1 character to right
Move cursor 1 "word" to left
Move cursor 1 "word" to right
Move cursor to start of line
Move cursor to end of line

History: Display previous command in recall buffer
Display next command in recall buffer

Deletion:
Delete 1 character to left of cursor
"
Delete 1 character at cursor
"
Delete to start of previous "word"
Delete to start of next "word"
Delete to start of line
Delete to end of line
Delete entire line

Toggle: Toggle insert/overwrite mode
--------------- -----------------------------------------


[A "word" is delineated by blanks or the start/end of a commandline.] As a
general rule of thumb then, is used to move along a commandline
while deletes the corresponding group of characters.

After you've worked for a while you may want to list commandlines
entered earlier. In this case invoke RECALL with the '-l' option, and the
current buffer contents will be displayed. You can redirect this output to
a file, printer, or even another program using DOS' redirection characters
'>', '>>', and '|'.

Like any good memory-resident program RECALL can be removed
completely from memory - just specify the '-r' option. RECALL will sense
whether it is the last TSR to hook into the main DOS interrupt (21h) and
abort if not.




If You Have Any Trouble
-----------------------


RECALL will attempt to let you know of any problems that arise. Here
are the possible error messages and how you should deal with each:

recall: illegal option -- x.
- Type "RECALL -?" for a list of valid options.

recall: already resident.
- RECALL found a copy of itself already active in
memory. Use the '-r' option to remove it if
that's what you want.

recall: memory control blocks corrupt.
- DOS detected an error when RECALL tried to free
its environment block. Your machine was likely
left in an unstable state by some earlier
program.

recall: not yet installed.
- You must install RECALL before you can remove it
from memory or list commandlines in its buffer.
This may also arise if you install some other
TSR after RECALL which intercepts INT 21h; in
this case you must remove the other TSR first.

These messages are written to the standard error device. In this way, they
won't disappear down a pipe or into a file when redirecting RECALL's
output.

Additionally, RECALL uses a return code to convey information about
the success or failure of its operation. Possible return values are:

Code Meaning
---- -------
0 RECALL was successfully installed or removed
1 Help message was displayed
10 Installation failed
20 RECALL has not yet been installed

You can test for these codes using the ERRORLEVEL construct in a batch file.




Requirements
------------


TifaWARE RECALL should run properly on any machine operating under
MS-DOS v2.xx or later. PC compatibility should not be a concern unless
your system uses something other than extended codes to represent keys on
the numeric keypad. It requires less than 2.5K of memory.

I regularly work with RECALL in a variety of environments - including
DESQview, PC-LAN, PolyShell, and MKS Toolkit. [Of interest to DV users is
the fact that RECALL does not churn thru CPU cycles while waiting for
keystrokes and can be loaded into high memory with LOADHI.] While it is
impossible to test RECALL in every possible configuration, I believe the
techniques used here are fairly standard and should not lead to problems
with other, well-behaved TSRs, shells, or operating environments.




Who Owns It?
------------


I am releasing this implementation of RECALL into the public domain.
Since my involvement with MS-DOS began in 1984, I've been a heavy user of
public domain software. Public domain software is a terrific idea. For
the most part, programs are useful and the source code instructive ... all
at no cost! With this small contribution to the public domain I hope to
pay back, in some sense, my gratitude to those other programmers who have
made my computing so much easier.

As a public domain program, RECALL carries no obligation on my part
to support users or provide future upgrades. I have tried to write clean
code and believe it to be "bug-free". Nevertheless, you must use this
program ***AT YOUR OWN RISK***. I strongly urge you to scan the source
code yourself, make any desired changes, and recompile the program, if
this is possible. If you make this standard practice with newly acquired
public domain software, you'll not only protect your system from worms and
viruses but also get a better feel for exactly how each program works!

As author of RECALL, I ask of you two things: First, if you
distribute this program, please keep together my original source code,
documentation, and executable. This just makes it easier for others to
use the software. Second, let me hear what you think of RECALL. You don't
have to send any money, just comments and suggestions.




Kudos
-----


Many thanks to Borland for v2.0 of its stand-alone debugger, which
greatly reduced the time spent developing this program. I highly recommend
it, especially if you plan on developing TSRs or device drivers.





George A. Theall

TifaWARE
506 South 41st St., #3M
Philadelphia, PA. 19104
U.S.A.

+1 215 662 0558

[email protected] (Internet)