Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PROGRAMS / UTILS / MEMORIA / PKII_127.ZIP / ANSI.DOC next >

Wrap

Text File | 1989-06-30 | 28.7 KB | 527 lines

ANSI.MOD Documentation May 1989 Version 1.24 Copyright 1988 by John H. Brooks. All rights reserved. Permission is granted to quote or distribute copies of this documentation separately, and the entire, unaltered POWERKIT II package. DISCLAIMER: This software is sold "as is." No warranty is given, either express or implied, that any specific POWERKIT feature will work on any particular machine. The manufacturer will not be liable for any damage caused by the use of POWERKIT. The names of hardware and software products, and companies mentioned in this document are trademarks or service marks of the respective companies. FORWARD: Welcome, let me tell you what this ANSI.MOD documentation does NOT contain. Although ANSI.MOD supports most of the ANSI X3.64 and VT100 "escape" sequences, not all of them will be described here. Just remember that ANSI.MOD will do the job for you, should you have an application pro- gram that requires VT100 emulation, or ANSI.SYS be loaded. Also, ANSI.MOD has many helpful routines that can be used by other programs, and these will not be mentioned here either. Instead, for those of you who might wish to write your own "module", or to delve into the esoteric mysteries of ANSI "escape" sequences, there is a technical reference manual available to all registered users of POWERKIT II. I have placed the "module" format for executable TSR (and device driver, ANSI.MOD is the console device driver*) files in the public domain, and any software developer, commercial or shareware, may use it, free of royal- ties. You may also take advantage of ANSI.MOD's superior routines in your programs. There are some restrictions, and you MUST contact me for approval, and for the specifics of this offer. WHAT IS ANSI.MOD? ANSI.MOD performs three major tasks (the keystroke buffer, with view-port, is a separate program). First, it is a replacement for the rather inadequate MS/PC-DOS console that controls your screen and keyboard. The DOS console's inadequacies are the reason every major application package handles its own I/O to/from the screen and key- board. Since each program handles this I/O a bit differently, you can * - For you "techies", ANSI.MOD (when active, and it's simple to turn it on and off) is the highest "CON" link in the device driver chain, is carried in the "list of lists" as the console driver, takes over INT 29h duties, and is the "file" that answers to "handles" 0, 1, and 2. Page 2 blame the poorly designed DOS console for the fact that some of your favorite pop-up TSR's (terminate, but stay resident programs) don't work inside some of your applications, and why some TSR's don't work very well with other TSR's. Thus, a major goal of the POWERKIT II design is, at least, to get a special class of TSR's, called "modules", to COEXIST amicably. To this end, ANSI.MOD provides a set of keyboard handling and screen updating routines, that are quite simply the best in the business. ANSI.MOD can replace an entire 80x25 screen, 40 times a second, on a standard 4.77 Mhz PC. Second, ANSI.MOD is a replacement for the equally laughable ANSI.SYS that came in your DOS package. It has a far larger set of the ANSI X3.64 and VT100 escape sequences, plus a few that ANSI never heard of. The commands represented by the escape sequences work under much more diverse conditions than do the corresponding ANSI.SYS commands, and in many instances, the same command does many more things than its ANSI- .SYS counterpart. To cite an example, the old ANSI "keyboard redefine" sequence did indeed replace one character by one or more other characters, giving ANSI.SYS a "MACRO" capability, sort of. But, the key redefinition acted ONLY at the DOS prompt (well OK, in DEBUG and EDLIN too). When you entered an application, the key reverted to its former self. ANSI- .MOD produces true MACROS that are available at the touch of a key, all the time. Furthermore, you can attach a comment or description to each of your MACROS, to remind you of some important fact about them. There is a way provided to show this comment, and also a means to move this MACRO to a different key (you'll see why later). Another feature unique to ANSI.MOD's MACROS is that ANSI escape sequences can be embedded in them. Thus, MACROS can be used to com- mand your communications port (dial the phone, for example), or printer, or even to define other MACROS (or delete!!, even themselves). Finally, MACROS can be defined at any time, because ANSI.MOD pro- vides "hot" key access to the ANSI sequence parser, replacing "PROMPT $e [" (ALT-ESC is the default, and FYI, all hot keys for POWERKIT II modules are just special types of MACROS, the help screens for the mod- ules are the above-mentioned comments, and the hot key can be moved just like any other MACRO). The old, unhandy "PROMPT $e [ ... " method is still available for batch file use, etc (but don't put "ECHO OFF" in that batch file, use CTTY NUL, then CTTY CON to restore the display). Oops, I almost forgot, an ANSI.MOD MACRO can contain sub-macros (to 10 levels deep), and these are expanded when the outer MACRO is being called, not when the outer MACRO is being defined. This not only saves space in the MACRO buffer, but the sub-macro(s) can be ALTERED between calls to the outer MACRO. I'm sure you will discover many uses for this sophisticated capability. Speaking of space, ANSI.MOD MACROS use only a single byte for most key- strokes, except "extended" ASCII codes (these are two byte codes whose first byte is 0, or E0h). "Problem" codes (such as control codes) are handled in software. This results in a significantly larger program, but the reward is, ANSI's buffer will hold almost twice as much inform- ation, in the same space, as some other "KEY" or "ANSI type" programs. Page 3 This brings us to a second important goal of POWERKIT II, STANDARD- IZATION!!!. All good word processors, spreadsheets, data "basers", provide many of the same helpful operations, like SEARCH, REPLACE, COPY, MOVE, DELETE, to name a few. The only trouble is, they each use different keystrokes to accomplish these tasks, and YOU have to REMEM- BER which keystroke combination goes with which program. NO MORE, just create a batch file for each of your programs. The batch file will create MACROS that move these operations to the same keys in all the programs -- call the program -- then "uncreate" the MACROS (yep, I forgot that too, you can delete MACROS) after exiting the program. Lastly, ANSI.MOD is the traffic cop that mediates potential conflicts between POWERKIT II modules, recognizes hot keys and calls the associ- ated module, disables one when another pops up on top of it (to 4 lev- els deep), interprets their "command" keys for them and calls the proper routine, sends them keystrokes when asked, pops up their help screens when F1 is pressed, provides many other useful routines (PKII- .MOD is several hundred bytes smaller because of these routines). Now for perhaps THE most AMAZING fact about ANSI.MOD. In its smallest configuration, with a 256 byte MACRO / ANSI sequence buffer, ANSI.MOD requires slightly over 5k bytes! and this leads us naturally to a third important goal of the POWERKIT II design, SAVING SPACE !!! The space savings provided by the remarkable module design is described in PKII.DOC, but ANSI.MOD also plays its part. The three goals mentioned above are intermediate to the FINAL goal, which is to SAVE MS/PC-DOS!!! (from itself, mainly). It's just too LOUSY an operating system not to need a great deal of help to survive. And survive it SHOULD; consider the alternatives; multi-megabyte, multi-user, multi-tasking UNIX and OS/2! Sure, they're powerful oper- ating systems, but I question whether even most "power users" need them. What I believe IS needed is a communications program, a smallish one, that will operate in the background, to process your Email, UL and DL files, and such (MIRROR II does a good job, but consumes 150k+, and THE INVISIBLE LINK has the right idea, does a partial job in only 29k of memory, could use more fine tuning); a print spooler to drive your printer in the background (PRINT comes with DOS, and is one of the best there is); a small, not too sophisticated foreground/background dual-tasker to handle a compute-intensive process (like a spreadsheet re-calc) in the background, and an I/O intensive task (like a word pro- cessor) in the foreground; ANSI, PKII.MOD, and a few other tiny, inex- pensive, indispensable, POWERKIT II modules to help you cope with DOS. Well, I've spoken my piece, now let me hear from YOU (please send money too). Does this approach to Personal Computing make any sense at all to you? INSTALLATION: Though it is far from being "just another module", ANSI.MOD can be loaded (and unloaded) like all other modules, by typing: LOAD C:\PKII\ANSI.MOD (instructions to ANSI.MOD may go here) Page 4 Of course, this assumes you have previously created the \PKII directory on the "C" (or "A") drive, and copied ANSI.MOD into it. The easiest way to do this is to run POWERKIT II's "INSTALL" program (see the in- structions in README.1ST). IMPORTANT NOTE: ANSI.MOD MUST BE LOADED BEFORE MOST OTHER MODULES !!! ANSI.MOD has two switches that may be set at load time (if you don't like the default values, otherwise don't do a thing). For example: LOAD C:\PKII\ANSI.MOD /m100/j0 ^ blank space will set aside 25,600 bytes for MACROS and ANSI sequence parsing (the default is 2048 bytes), and eliminate ANSI.MOD's help screen. * /Mn, n = 1 to 237 (approx.), tells ANSI how many 256 byte sections of memory to reserve for MACROS and ANSI escape sequence parsing. * /Jn, n = 0 or 1, turns ANSI.MOD 's help screen off or on. NOTE: You must reserve space, in ANSI.MOD's MACRO buffer, for module help screens. If the screen for PKII.MOD is attached, in /Mn, n must be 4, or higher. ANSI comes to you with the default set at 8 (i.e., 2k of MACRO buffer space), so there's no need to worry when you first load ANSI.MOD and PKII.MOD (2k will hold both help screens). ANSI COMMANDS: All ANSI escape sequence commands begin with the "escape" char- acter, which is a decimal 27. The next character is almost always a left bracket (a "["). The real "meat" of the command then follows those preliminaries. As was stated earlier, ANSI commands can be ac- tivated from the keyboard, at any time (not just at the DOS prompt), by pressing ALT-ESC (press the "ESC" key, while holding down the "ALT" key). ALT-ESC acts as the "27" and the"[". The "meat" is either a series of numbers, separated by semicolons (like 1;2;33;44), or a se- ries of characters, enclosed by single or double quotes (like 'abc' or "abc"), plus a final upper or lower case character (must be outside of any quote marks). That final character of the sequence tells the ANSI command interpreter (hereafter referred to simply as ANSI) what to do. MACRO RELATED COMMANDS: To a Greek (and a select few others), "macro" means "large". In computerese, a MACRO is a string of one or more charac- ters, that are sent to a display, a file, printed on a printer, or sent to a modem, after a (single) key is pressed. At this very moment, I'm using MACROS to enter the words "ANSI.MOD" (I press ALT-2), "ALT-ESC" (I press ALT-3), and "MACRO" (I press ALT-4), into this document. CREATE A MACRO: The final character (mentioned above) that tells ANSI to create a MACRO is lower case "p" (upper case "P" means something en- tirely different to ANSI). Creating a MACRO with ANSI.MOD is almost as easy as (or easier than) it is with those well-known (and costly, in PRICE and MEMORY) "KEY" and "ANSI" programs: The "quote" key is the key between the semicolon/colon key, and the ENTER (RETURN) key. Page 5 1. Press ALT-ESC (you should hear a beep) 2. Press the "quote" key (shifted or not) 3. Press the key to which the MACRO will be attached 4. Press the sequence of keys you wish the redefined key to represent 5. Press the "quote" key again (shifted or not, but the same as in step two above) 6. Press lower case p That's all there is to it. You will notice ANSI's view-port will open to show you the keystrokes you are typing (well not quite, it cannot show non-printing codes). If you need one or the other of the "quote" keystrokes in your MACRO, use the other 'quote' as the delimiter. If you need them both, end one "quote" sequence, press ";", press the other 'quote', press the "quote" you need, and continue. If you wish an ANSI escape sequence to be part of your redefinition, press ALT-ESC, followed by the ANSI sequence. Make sure you are inside the "quote" delimiters (see note below). Outside "quote" delimiters, you must use "0;1" to represent "ESC [". IMPORTANT NOTE: Pressing ALT-ESC a second time ABORTS an ANSI escape sequence, but not if you are inside the "quote" delimiters. DELETE A MACRO: To delete a MACRO, press ALT-ESC, "quote", the key to which the MACRO is attached, "quote", then lower case p. This causes the key to revert to its original function. Sorry, the only way to delete all MACROS, is to UNLOAD, then re-LOAD, ANSI. The reason for this, is that all module "hot" keys are MACROS too (including ANSI.- MOD's), and it wouldn't be wise to delete them. MOVE A MACRO: To move a MACRO to a different key, press ALT-ESC, "quote", the "old" key, the "new" key, "quote", then lower case k. Since module hot keys are MACROS, this procedure will also move a module's hot key. MACRO DESCRIPTION: You can include a description of what the MACRO does, when you define the MACRO, if you wish. After defining the MACRO, and pressing the "quote" key, but before pressing "p", press the "left single quote" key, enter your description, press the "left single quote" again, then press "p". Include carriage returns (the ENTER or RETURN key), when you want to start a new line, in your description. SHOW DESCRIPTION: To look at this description, press ALT-ESC, "quote", the MACRO's key, "quote", then lower case q. The description will pop-up on the screen, then disappear as soon as you press another key (the SHIFT key, for example). NOTE: This can be used to produce helpful information for you at the touch of a key. Create a "view-only" MACRO by putting the text you would like to see, in the description field, the MACRO's activation key, en- closed in quotes, then lower case q, in the execution field of the MACRO. Now, when this MACRO's key is pressed, the text will pop up on the screen, and disappear when the next key is pressed. TURN MACROS OFF/ON: Press ALT-ESC, "0", lower case "t" to disable all MAC- ROS, except ANSI.MOD's hot key. ALT-ESC, "1", "t", turns them back on. Page 6 IMPORTANT NOTE: The fact that ANSI.MOD waits until an outer MACRO is being called, before expanding sub-macros, creates a problem for which there is no completely satisfactory solution. Consider this: Suppose you at- tached the MACRO "a" to "a". In other words, define the key "a" to be itself. When "a" is pressed, ANSI.MOD will look at it, decide that it was redefined, and look up its redefinition. The characters in the re- definition will then be checked to see if any are themselves redefini- tions, AND DISCOVER THAT "a" IS. What has been created, is an infin- ite loop. To stop this, ANSI.MOD checks the stack of sub-macros cur- rently being expanded, and if it finds a sub-macro already on the stack that is the same as the one being checked, it will NOT expand the one being checked. FAST SCREEN MODE: ANSI.MOD is far from being a slow poke in putting characters on your screen. But sometimes, it can be even faster. DOS does some checking between sending characters to the screen. For instance, DOS checks for CTRL-C, which tells DOS to stop doing whatever it is doing. This checking can be turned off, thus speeding up screen writes. True, you will lose CTRL-C and CTRL-BREAK, but PKII.MOD's KEYPAD 5 (or SCROLL LOCK), ESC will still get you out of trouble. To enable ANSI.MOD's fast screen update mode, press ALT-ESC, then 1, then lower case "r". To disable this mode, press ALT-ESC, 0, lower case "r". CHANGE TEXT AND GRAPHICS MODES: Press ALT-ESC, n, lower case h, where n is the number of the text or graphics mode you wish to use. I use this mostly when some ignorant programmer has decided he knows more than I, about what mode I want MY display in, puts MY display into 80x25 color mode, when I want it to be in 80x25 Black & White. Note that n = 7 is not a text or graphics mode, but rather a "wrap" mode. If you don't wish characters to "wrap" at the end of a line, press ALT-ESC, 7, lower case L (l looks like 1). The option, n = 43, is not part of ANSI, but if you have an EGA (or VGA), it will put your display into an 80x43 (50 for VGA) text mode. The possible values for "n" are: 0 - 40x25 black & white 1 - 40x25 color 2 - 80x25 black & white 3 - 80x25 color 4 - 320x200 color graphics 5 - 320x200 black & white graphics 6 - 640x200 black & white graphics 7 - Automatic CR LF at end of line 8 - 160x200 color graphics (PCjr and Tandy 1000) 9 - ? 10 - ? 11 - ? 12 - ? 13 - 320x200 EGA color graphics 14 - 640x200 EGA color graphics 15 - 640x350 EGA B & W graphics 16 - 640x350 EGA color graphics Page 7 17 to 42 - ? 43 - Forty-three (50) line TEXT mode for EGA (VGA) (text only) ? - Means "perhaps" that number does something nice to your machine. If not, entering it may cause your machine to LOCK UP. CHANGE SCREEN COLORS, ETC.: Press ALT-ESC, P1;P2; ... ;Pk, lower case m, where the Pi's are numbers listed below. In other words, you are able to select more than one of the attributes listed below, in the same call to ANSI. Put semicolons between each number. Again, this is used when some stupid application messes up your screen. It always works after you exit the program, but some programs won't permit you to change colors while inside them. Note that option 9 lets you supply an attri- bute byte, thus can do the work of (almost all of) the other options. no param - makes current screen (low intensity) White, on Black 0 - return to White on Black background, no Bold, no Blink 1 - high intensity (foreground and border only) 2 - normal intensity, no color change, just dimmer foreground 4 - underline (monochrome adaptors only) 5 - blinking (in graphics modes, characters are XOR'ed) 7 - reverse video (XOR background & foreground, blink, bold unchanged) 8 - concealed characters (foreground = background, in color) 9 - The number entered after the 9 replaces current attribute byte (background & foreground colors, blink, and intensity) * 10 - Turn off cursor in graphics modes (this is the default) * 11 - Turn on cursor in graphics modes (VERY SLOW, use sparingly) * 12 - Turn off (detach) ANSI.MOD. MACROS, and many other things, still work. ANSI.MOD can still support the other modules. * 13 - Turn ANSI.MOD back on. 21 - Remove boldness 22 - Remove blinking and boldness (like option 0, but it works on color screens) 24 - Remove underlining (MDA only) 25 - Remove blinking 27 - Reverse video (same as option 7) 28 - Remove concealed characters (restore foreground) foreground colors 30 - black 31 - red 32 - green 33 - yellow 34 - blue 35 - magenta 36 - cyan 37 - white 38 - ERROR 39 - ERROR * - NOTE: At release time (1/31/89), options 10 through 13 sometimes had to be entered twice before they "took". Page 8 40-47 - Background colors (in same order as 30-37) 48 - ERROR 49 - ERROR 50-81 - Border colors (in same order as 30-37, except 51-blue, 53-cyan, 54-red, 56-yellow. 58-65 are high intensity.) COPY TO PRINTER OR MODEM: Use ALT-ESC, n, i, where n is a number listed below. These commands will usually be used in MACROS. For example, suppose your boss is too cheap to buy you a demon dialing telephone, and you MUST call your stockbroker quickly and often. If your modem has auto- dial capability, you can set up a MACRO to do this. Let's attach this MACRO to F10. Press ALT-ESC, "quote", F10, ALT-ESC (again), 2, i, ATDT5551212 (or whatever your broker's number is), ALT-ESC (yes, again), 6, i, "quote", p. Note: If your boss is too cheap even to install touch tone lines, change the "ATDT" to "ATDP". What did we do here? The first ALT-ESC gets ANSI's attention. The "quote" mark says that characters, rather than numbers, are to follow. F10 is the MACRO's key. The characters before the next "quote" will be explained later. The "quote" marks the end of the characters, and the "p" tells ANSI to attach those characters to the F10 key. Now here's what happens when you press F10. ALT-ESC starts the ANSI sequence to turn on copy to the modem. The "2" selects the modem. The "i" completes the ANSI sequence. From here on, everything that would normally go to the screen, goes to the modem instead. Thus, the "ATDT- 5551212" is sent to the modem, and the modem dials the number. The final ALT-ESC alerts ANSI again; the "6" deselects the modem; the "i" completes the command, and ANSI directs output back to the screen. The possible values for "n" are: 0 - Copy to printer (LPT1) 2 - Copy to modem (COM1) 3 - Copy from modem (COM1) 4 - Turn off copy to printer 6 - Turn off copy to modem 7 - Turn off copy from modem FAKE KEYSTROKES: How many times have you wished you could send instructions to an application you call from a batch file? Now you can. In the batch file that calls the application, on a line before the call, put: prompt $e["instruction 1";13;"instruction 2";13; ... etc. ... ;v Those "13"'s are carriage returns to separate the individual instructions (sometimes not needed). STANDARDIZATION: Suppose you have two word processors, one named "EDITOR", and one named "ED". One you use to dash off notes and memos, the other, for more serious work (not that your memos aren't serious). For the sake of simplicity, suppose the two have identical command structures, except that ED uses F8 to call up the "search" capability, while EDITOR uses F9. To get both programs to use the same keys for the same opera- tions, you must call one using a batch file. Let's call ED using the batch file, EDIT.BAT. Use either ED or EDITOR to create the following EDIT.BAT, batch file (note the CTTY command, in place of ECHO OFF. ECHO OFF disables the "PROMPT" command): Page 9 ctty nul - diverts output from display prompt $e[0;67;0;66p - turns F9 into F8 ed - calls the editor prompt $e[0;67p - after ED finishes, turns F9 back into F9 prompt $n$g - resets your "DOS prompt" ctty con - sends output back to display Now, when you wish to use ED, just type EDIT, and the F9 key will call the search facility. Perhaps some of you are thinking "what's this screwy `prompt $e[' no- tation?" Well, it's the screwy way DOS has provided you to access ANSI. I'll bet you recognized the "p" at the end of the first line, and guessed that a MACRO was being defined there. The "prompt $e[" is DOS's way of sending an escape (27, remember?),and a "[", to ANSI. The "0;67" is the (extended) ASCII code for the F9 key, and "0;66" the ASCII code for the F8 key. They have to be represented in this awkward manner (when using the PROMPT command only), because they are nonprint- ing characters (for printing characters, you would simply put in a "quote", then the characters, then another "quote"). Thus, the first line of EDIT.BAT turns F9 into F8. The second line calls ED. The third line isn't executed until you have exited ED, and it deletes the MACRO attached to F9. The fourth line tells DOS to make a prompt consisting of the current drive letter, followed by the symbol ">" (look familiar?). The following does the same thing, but without using "prompt ...", and also suppresses the irritating display of "echo off" when the batch file starts. Most editors will let you hold down ALT, then press keypad "2", then "7", to make the "" (escape) character: - make foreground = background (and save foreground) echo off - suppress display of batch file actions echo - restore foreground color echo 7;0;66p - turns F9 into F8 ed - calls the editor echo 7p - after ED finishes, turns F9 back into F9 echo on - restore display This method has the added advantage of not destroying your DOS prompt. I hope this (admittedly oversimplified) example gives some idea of how to lessen the memory circuit overload many of us endure, because every program we own does the same thing differently. Most DOS manuals have a table of ASCII codes in the back, for you to refer to in this endeav- or. Yes, these ANSI sequences are kind of tough to construct, but you need to create a batch file only once, for each of your most-used programs.