Documentation File Take.txt   (revised 5/15/88)

>>> Take.Com <<<

   - a memory resident screen line grabber for IBM PC work-alikes
        (optimized for use with terminal emulation programs)
   by Mark C. Smith  version 88.5 (test version)


Introduction
     There are many of us who spend a good portion of our PC time
     interacting with a remote computing network using some kind
     of terminal emulator software.  Unfortunately, the terminal
     emulators I use do not typically have a facility for the
     re-entering lines that are still on the screen or in the
     conversation buffer.  The program Take was designed to provide
     line re-entry with nearly any terminal program (Take is being
     tested with Window - University of Michigan, Procomm 2.4.2, and
     Kermit 2.29b).

     Take is memory-resident and provides some interesting features:
      - Editing of a potential re-entry line right on the screen in
         the place the line appears (complete set of editing functions)
      - Active indication of position and insert status using a normal
         cursor.  Insert on is indicated by a full height (block-style)
         cursor.
      - The ability to suspend itself to pass a keystroke pressed
         when Take is "popped up" that Take does not recognize.  This
         allows scrolling of the communication program's text buffer
         without turning Take off and back on again (by passing
         Page Up and Page Down to the program, for example).  This is
         probably Take's most unique and difficult feature that Take
         implements on top of multiple programs using memory resident
         techniques.
      - Transparency to the underlying program.  Edited lines are
         restored on screen, and cursor state is restored as well as
         is possible.
      - Facilities to turn off a resident version of Take and to
         re-start a version turned off (but only one copy of Take
         can be in memory, even if another is turned off).
      - Tight code and fast operation. Take is written entirely in 8086
         assembler, and screen read and writes are directly to video memory.
      - User configuration option for all keys used by Take and for some
         additional options.  This will minimize interference with other
         resident programs.

How To Get Take Up And Running
     Take requires an IBM compatible machine, and should run
     on any PC,XT,or ATs that have a CGA,MDA,EGA,or VGA display
     adapter.  Take does directly access the video display
     memory, so this may cause problems in some clones (not
     likely though).  It should run under DOS version 2 or
     greater.  The resident portion of Take steals less
     then 1900 bytes of memory (about half the code for Take
     is for configuration modification/display and installation).

     Take is bundled in the .arc format, which means that it
     must be unArced to be useful.  If you are reading this
     documentation (take.txt) you must have already accomplished
     the use of one of the arc programs to extract the files.
     The files contained in the take.arc file are:
         take.txt      - this brief documentation you're reading now
         take.com      - a version of take configured "generically"
                         (no prefix or suffixes; CGA Snow=Yes)
         take_p.com    - a version of take configured for Procomm.
                         (prefix=ALT-F6,suffix=ESC,CGA Snow=No)
         take_w.com    - a version of take configured for Window
                         (communication program of the University
                          of Michigan. prefix=suffix=none,CGA Snow=No)
         take_k.com    - a version of take configured for Kermit.
                         (prefix=none,suffix=END,CGA Snow=No)
     Note than all the _? files were made just by running take.com with
      the configure option.  They are provided as a convenience and as
       examples of use of the prefix and suffix sequences.

     The only file you need is one of the .com files.  I suggest copying
     one of the _p,_w,_k files to take.com if you only need one of them.
     The syntax for invoking Take is:
         take -{option}
   or    take /{option}   where {option} is one of BCDIOR (bcdior)
     Action             Syntax    Effect
     ------             ------    ------
     install            take -i   Take is installed (memory resident) if it
                                   is not already installed.  Header and
                                   author contact information is displayed.
     brief install      take -b   Same as i(nstall), except most messages
                                   are suppressed.
     display config.    take -d   Displays the current configuration of Take.
                                   This mostly consists of key definitions.
     configure          take -c   Invokes the interactive configuration
                                   process to set keys and more.
     turn off           take -o   The version of Take resident in memory
                                   is disabled (effectively off).
     restart (turn on)  take -r   The version of Take resident in memory
                                   is re-enabled.
     usage info.        take      (No option specified).  A usage message is
                                   displayed.  If not installed in memory
                                   yet, you will be asked if you want to
                                   install Take.

Using Take
     Upon installation, Take becomes memory resident and checks in
     the background for the hotkey to be pressed (the default is
     ALT-F9).  Typically, you will want to install Take (run with
     -i or -b option) and then run your favorite terminal emulation
     program.  Any time you wish to use Take to re-enter a line that
     is on the screen or in the conversation buffer, press the hotkey.
     As long as the video is not in a graphics mode, Take will pop up.
     (Note that Take cannot and will never pop up in a graphics mode).

     Take will first send a prefix keystroke sequence to the program
     currently running before popping up.  This prefix feature is for
     programs such as Procomm that require some keystroke(s) to invoke
     conversation buffer scroll-back mode.  (In Procomm, the prefix
     is a single key: ALT-F6).  The prefix can be nothing (as for
     Kermit).  Then Take will place the cursor at the beginning of
     the line above the one it was last on and wait for keystrokes.
     There are several general types of keys that Take handles in
     different ways:

       Cancel Key (configurable, default is ESC) - Take will pass a
                    suffix keystroke sequence to the program running
                    underneath and then return control to that program.
                    The suffix sequence is used to restore the program
                    to its previous state.  (In Procomm, ESCAPE is used
                    to drop out of scroll-back mode; in Kermit an END
                    is used to return to the end of the conversation
                    buffer).

       Grab Key (configurable, default is RETURN) - Take will pass
                    the suffix keystroke sequence (see above), and then
                    all of the text from the left of the line the cursor
                    is on to the last non-blank character in the line.
                    Presently, no trailing Return is sent at the end
                    of the line.  This option may be added in the
                    future.

       Editing Keys (configurable) - Take will perform an editing
                    action on the cursor line.  Possible actions and
                    defaults:
                     Default Key      Action
                     -----------      ------
                     HOME             Move cursor to beginning of line
                     END              Move cursor to end of line
                     Left Arrow       Move cursor one position to the left
                     Right Arrow      Move cursor one position to the right
                     INSert           Toggle Insert/Overwrite mode
                                       Insert mode is indicated by a full
                                       height (block-style) cursor
                     DELete           Remove the character under the cursor
                     Backspace        Rubout to the left of the cursor
                     Ctrl-END         Erase to end of line (from cursor right)

       Line Movement Keys (configurable) - Take restores the line the cursor
                     is on, removing any changes made and moves the cursor
                     up (default=Up Arrow) or down (default=Down Arrow) a
                     line and to the beginning of the line.

       Other Keys (anything else!) - Take attempts to pass the key through
                     to the underlying program (terminal emulator,etc.)
                     so that the program can react to the key.  After the
                     key is accepted by the program, Take will regain
                     control and pop back up and place the cursor at
                     the beginning of the screen line Take was last on.
                     Between passing the keystroke and popping back up,
                     any changes to an edited line are restored.  This
                     tricky feature (the passing of keys Take doesn't
                     itself use) allows the scrolling of the conversation
                     buffer while line re-entry is taking place (much
                     like some real terminals allow).  Page Up and
                     Page Down in Procomm, Kermit, and Window all work
                     properly.  Other terminal program functions should
                     also work (the page up and down is probably the
                     most obviously useful, though).

Configuring Take
     Take, unlike the vast majority of PC programs, allows for complete
     user configuration.  This includes the "hotkey" to pop-up take,
     line editing keys, prefix and suffix keystroke sequences, and more.

     The -d option can be used to display the current
     configuration and the -c option is used to begin the interactive
     configuration process.  The procedure should be fairly self-
     explanatory, since you are prompted for each key.  The tricky
     parts involve the prefix/suffix sequences and the CGA snow question.

     Prefix and suffix sequences are emitted by Take before popping
     up and after Take is done executing a re-entry operation (or is
     cancelled).  The sequences can be up to 10 keystrokes in length
     at present (this should be plenty for most programs, I hope).
     During configuration of the suffix or prefix, you can enter any
     series of keystrokes terminated by an ALT- (ALT Minus).  This
     implies that ALT- itself can not be part of the sequence.  Let
     me know if this is a problem, since the terminator is not at
     present user-configurable.

     Take asks a "CGA with snow problem" question near the end of
     the configuration process.  Answer y (for yes) if your machine's
     video adapter is an original IBM CGA or a clone with the dreaded
     snow problem.  If you are unsure, try Take with n (for no) and
     see if the screen is filled with a snow-like pattern when you
     do editing on the screen with Take popped up.  If the snow appears,
     you want to say yes.  This option is only important if your
     program actually runs using a CGA. It is ignored for any other
     video adapter (MDA,EGA,VGA).

     At the end of the questions, you will be asked if you wish to
     clone take.com onto disk.  Actually, under DOS version 3 or
     greater, Take extracts the full pathname of the program you ran
     and will write over that file with the newly configured version
     if you respond y (for yes) to this question.  If you say n (no),
     the new configuration is discarded.  Under DOS 2.x, the file
     written is always take.com in the default path (since I couldn't
     find a reliable way to get the actual pathname in these DOS
     versions).  The file will be created if necessary.

     If you want to have different versions of Take configured for
     various terminal programs, you can rename and copy the Take.com
     file and then configure the copies independently, as was done for
     the versions provided in the take.arc distribution file.

Using Take With Other Programs
     There is no reason why Take should not work with your favorite
     text editor, word processor, or any other text-mode program
     except for the problems inherent in a memory resident program
     interfering with the program it pops up over.  For example,
     Take seems to work o.k. (not perfectly) with the Turbo Pascal
     3.x editor, but calling up Take under Microsoft Word 4.0 locks
     up my machine.

     The only thing you can do is configure Take as best you can
     for the program and try it out.  Take is (obviously) optimized
     for terminal emulation programs, since it was designed with
     that use in mind.  It also should work at the DOS command prompt.

Technical Information
     (This is provided only for those interested or in case Take
     interferes with another memory resident program and you
     might want to try to guess why).

     When Take is installed, it chains onto interrupt vector 16h
     (the BIOS keyboard service routine).  Virtually all of Take's work
     is done from within this service routine. Int. 16h is called by nearly all programs to request keystrokes or
     status information.

     When Take is looking for the hotkey, it calls the old int 16h routine
     and checks all keycodes returned to see if the hotkey is pressed. If so,
     a request flag is set to indicate to Take that it should pop up at the
     next available opportunity.  The hotkey is NOT extracted from the stream
     of keystrokes being returned by Int. 16h, but if the hotkey is intercepted
     during a keyboard status call, Take will probably pop up quickly and
     absorb the hotkey itself.

     The main routine for Take is called from within int 16h also, but
     it is called before the old int 16h routine checks for actual keys
     (actually only when service 0 or 1 - keystroke or status is called).
     If the request flags is set (or Take has been suspended), control is
     passed to the main Take routine.

     When Take is operating in this main routine, it is effectively in
     control and the editing and cursor control keys are active.  Int. 16h
     is also used to pass a series of keystrokes to a program for the prefix,
     suffix, or the text grabbed off the screen.

     It is worth noting that programs that directly take control of the
     keyboard and get keystrokes via int. 9 or those that examine scan
     codes returned by int. 16h will not work properly with Take.  Take makes
     no attempt to calculate a scan code for ascii text sent as keystrokes
     grabbed off the screen.  Take just sends a bogus scan code of 0ffh in
     all cases.  Fortunately, there are very few such programs (or at least
     non-memory resident ones) that seem to do either of these things.  Take
     can also suspend itself in order to pass the "other" keys to an underlying
     application so that scrolling of the communication buffer or any other
     normal operation can be performed while Take is suspended.  This is all
     accomplished with difficulty and trickery from within the same interrupt
     16h, the BIOS keyboard service routine.

     Take requests keystrokes from int. 16h like most other programs,
     and screen reading and writing is done directly to video display
     memory for maximum speed.  Take attempts to recognize CGA,MDA, and
     EGA.  VGA is treated like EGA, which should work.  Take even examines
     display column width and vertical row height, and in theory will
     work in EGA 43 line mode and other oddities.

     All messages and text that Take writes to the screen during the
     installation process are written to DOS standard output.  This
     implies that you can completely suppress the messages (if you
     install Take in a batch file) by using redirection:
       e.g.:   take -i >nul
     Be careful though - input during configuration, etc. is obtained
     NOT through DOS standard input, but by using keyboard BIOS routine
     16h (as all keyboard input in Take is).

     As mentioned earlier, the present source code is a little over
     1300 lines of 8086 Microsoft Masm 4.0 compatible assembler (now
     being assembled with Masm 5.1).  The source code is not distributed
     along with the executables for various reasons, mainly because I
     don't want the program to be hacked and modified (unless I do it)
     while my name is attached.  If you have a good reason to want to
     see part of the source code, or just want to know how something is
     done, contact me and we can work something out.

Known Problems With Take/Things To Look Out For
     - Support for VGA (MCGA) has only been superficially tested.
         Other video adapters and various brands of EGAs, etc. may
          possibly cause problems.  I hope not, but let me know.
     - Some versions of DOS may cause problems.  Take seems to have
         no problems with IBM DOS 2.10 and 3.10, Zenith DOS 3.2, and
         some others,  but I can't reasonable test DOS version out there.
         Take relies on DOS for very little; the cloning of the program
         itself is where DOS is most important.  The method I use to
         find the pathname to clone to under DOS 3.x may not be a
         mandated method (it doesn't work for 2.x) and may cause some
         problems.

Future Desired Enhancements
     - Modify the configuration routine to show the current definition,
        provide an option to leave unchanged, and to modify an already
        memory resident version of Take.  Fairly easy to implement, but
        the configuration/display code is ugly right now and should
        be cleaned up first.
     - Provide a configurable option to automatically append a RETURN to
        the end of a grabbed text line.  Easy to do; the most difficult
        part is again the configuration.
     - Provide a configurable option to display an indicator on the screen
        that Take is actually active (it could change when Take is suspended
        and of course disappear when Take is popped down fully).  I had this
        in, but it really needs to be configurable as to where it will
        appear on the screen.
     - Option to uninstall.  The current "turn off" and "restart" work
        to prevent conflicts with other programs you might run after ending
        a terminal session, but memory is still occupied.
     - Anything else anyone might request.  I am open to suggestions!

About the Author/How To Contact Me
     Mark Smith is currently a senior at the University of Michigan and
     will be graduating with a B.S.E. in Computer Engineering in the
     summer of 1988.  He has owned a Zenith 158 XT work-alike for nearly
     three years, and is now finding its 8 Mhz 8088, CGA screen, and
     20 MB hard disk lacking. Primary interests are not in software, but
     in hardware strangely enough, and he could never save enough time
     in the course of the rest of his life using Take to re-enter lines
     to balance the time spent programming it.  Other interests include
     any kind of sport, reading any kind of book, and the outdoors.

     I can be reached for questions, comments, or whatever...

      via electronic mail:  mark_smith@um.cc.umich.edu

      through June, 1988:
         815 S. State Street Apt. #12
         Ann Arbor, Michigan 48104

      after July 1st:
         2225 Shattuck Road
         Saginaw, Michigan 48603

     As the program echoes, this version is free to use for any
     non-commercial purpose.  In particular, any unauthorized sale,
     distribution of a modified version, or distribution without
     this accompanying documentation is disallowed.  When in doubt,
     use your own good judgement.
