Simtel MSDOS 1992 December

home *** CD-ROM | disk | FTP | other *** search

/ Simtel MSDOS 1992 December / simtel1292_SIMTEL_1292_Walnut_Creek.iso / msdos / modem / take.arc / TAKE.TXT < prev

Wrap

Text File | 1988-05-28 | 21KB | 363 lines

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.