RECALL, v1.2
                                -------------
                                from TifaWARE




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

     Version 1.2 fixes a bug that would rear its nasty head if you 
redirected stdin; eg, "DEBUG < script.dbg". Basically, I hadn't bothered
to strip linefeeds from the commandline as DOS does. Just after I fixed
this problem I came across Ralf Brown's proposal for an alternative
multiplex interrupt. By implementing it I'm now able to test much more
reliably whether RECALL is loaded. Finally, I've added support for IBM's
Interrupt Sharing Protocol, which permits removal of TSRs in arbitrary
order. [Of course, your other TSRs must support this protocol too for it
to be of much use.]

     Version 1.1 was the first public release of RECALL.




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


     RECALL is a memory-resident commandline editor and history utility.
If you've been using DOS' built-in yet primitive editing keys until now 
you'll be pleasantly surprised. With RECALL you get improved commandline
editing as well as a 1K buffer for keeping track of old commandlines.

     Once installed in memory -- it takes about 2.5k -- RECALL intercepts
requests for buffered input and processes them itself. Typically DOS uses
this type of input to read commands at the familiar "C>" prompt; DEBUG and
LIST use it too. Most keystrokes are saved in a buffer while you edit the
commandline and then passed along when you hit <ENTER>. 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 simple. Once 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.2a, 11/16/91 - 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, at least remember how to display
this help message.]

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

     It's easiest to install RECALL from your AUTOEXEC.BAT. This way
you'll have it available always. Note that RECALL does not care where in
the TSR chain it lies, except perhaps if you want to uninstall it later.
If you do not install RECALL at boot-time though, remember it's unwise to
install any TSR while "shelled out" 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 as you did
before. Only now, RECALL's power is just a keystroke away. Here's a
summary of its features:


          Key                 Action
          ---------------     -----------------------------------------
Movement: <LEFT>              Move cursor 1 character to left
          <RIGHT>             Move cursor 1 character to right
          <PGUP>              Move cursor 1 "word" to left
          <PGDN>              Move cursor 1 "word" to right
          <HOME>              Move cursor to start of line
          <END>               Move cursor to end of line

History:  <UP>                Display previous command in recall buffer
          <DOWN>              Display next command in recall buffer

Deletion:
          <CTRL><LEFT>        Delete 1 character to left of cursor
          <BS>                "
          <CTRL><RIGHT>       Delete 1 character at cursor
          <DEL>               "
          <CTRL><PGUP>        Delete to start of previous "word"
          <CTRL><PGDN>        Delete to start of next "word"
          <CTRL><HOME>        Delete to start of line
          <CTRL><END>         Delete to end of line
          <ESC>               Delete entire line

Toggle:   <INS>               Toggle insert/overwrite mode
          ---------------     -----------------------------------------


[A "word" is delineated by blanks or the start/end of a commandline.] As a
rule then, <KEY> serves to move along a commandline while <CTRL><KEY>
serves to delete 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 to
display the current buffer contents. 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 from
memory. Just specify the '-r' option. RECALL will sense whether it's safe
to unhook itself and abort if not. RECALL should only balk if some other
TSR you have loaded doesn't follow IBM's Interrupt Sharing Protocol.




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


     RECALL will let you know of 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: DOS v1 is not supported.
          - Sorry, you'll have to upgrade.

     recall: unable to go resident.
          - Either RECALL found a copy of itself already 
            active in memory or you have over 255 TSRs
            loaded. Remove something.

     recall: unable to remove from memory.
          - Some other TSR was installed later that does
            not share interrupts.

     recall: not yet installed.
          - You must install RECALL before you can list
            the commandlines in its buffer or try to
            uninstall it.

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
     5         Incorrect DOS version
     10        Installation failed
     20        Removal failed
     25        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 on any machine running DOS v2.x or better.
Don't worry about PC-compatibility unless your system uses something other
than extended codes to represent keys on the numeric keypad. It requires
about 2.5K of memory. 

     I regularly work with RECALL in a variety of environments - including
DESQview, PC-LAN, and PolyShell. [DV users take note: RECALL does not
churn thru CPU cycles while waiting for keystrokes and works fine with
LOADHI.] While it is impossible to test RECALL in every configuration, the
techniques used here are standard and should not lead to problems with
other well-behaved TSRs, shells, or operating environments.




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


     I am releasing this program into the public domain. Since 1984 I have
used public-domain software extensively, and I find it to be a terrific
idea. Most programs are useful, and the source instructive. And they cost
nothing! With this small contribution to the public domain I hope to pay
back my gratitude to those other programmers who have made my computing so
much easier.

     However, this program carries no obligation on my part to support
users or provide future upgrades. I try to write clean code and believe it
is "bug-free". Nevertheless, use this program ***AT YOUR OWN RISK***. Scan
the source yourself, make any desired changes, and recompile the program,
if possible. Make this standard practice with newly-acquired software and
you'll not only protect your system from viruses but also get a better
feel for exactly how programs work!

     As author of this program, I have two requests: First, please keep
together the original source code, documentation, and executable if you
distribute the package. This just makes it easier for others to use the
software. Second, let me hear what you think of it - I'd appreciate a
postcard with your comments. Enjoy!




Kudos
-----


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





                          George A. Theall

                             TifaWARE
                         610 South 48th St
                      Philadelphia, PA.  19143
                              U.S.A.

                         george@tifaware.com
                       http://www.tifaware.com/