TopWare Tools

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

/ TopWare Tools / TOOLS.iso / tools / top1261 / ansiplus.doc < prev next >

Wrap

Text File | 1992-09-08 | 81.9 KB | 2,067 lines

ANSIPLUS Enhanced Console Device Driver User's Guide, Version 2.04 Shareware Documentation September 8, 1992 COPYRIGHT (C) 1991, 1992 by Kristofer Sweger P.O. Box 378, Larkspur, CA 94977 All Rights Reserved The ANSIPLUS console device driver and supporting utility programs are Copyrighted (C) 1992 by Kristofer Sweger. This software and accompanying documentation are protected by United States Copyright law and also by International Treaty provisions. The ANSIPLUS computer program and this documentation may not be reproduced, copied, disclosed, or transferred in any form (machine-readable or photo-copy included), except as provided here under "Limited License" (see page 3), without the express prior written approval of the author. U.S. Government Information: Use, duplication, or disclosure by the U.S. Government of the computer software and documentation in this package shall be subject to the restricted rights applicable to commercial computer software as set forth in subdivision (b)(3)(ii) of the Rights in Technical Data and Computer Software clause at 252.227-7013 (DFARS 52.227-7013). The Contractor/ manufacturer is: Kristofer Sweger, P.O. Box 378, Larkspur, CA 94977. DISCLAIMER OF WARRANTY Kristofer Sweger makes no warranty of any kind, express or implied, including, without limitation, any warranties of performance, merchantability and/or fitness for a particular purpose. This software and accompanying documentation are provided "as is," without warranty of any kind. The entire risk as to results and performance is assumed by you. Kristofer Sweger shall not be liable for any damages, whether direct, indirect, consequential or incidental arising from a failure of the ANSIPLUS programs to operate in the manner desired by the user. Nor shall Kristofer Sweger be liable for any data, property or other damages which may be caused directly or indirectly by use of or inability to use the software, even if Kristofer Sweger has been advised of the possibility of such damages. In no event shall the liability for any damages exceed the price paid for the license to use the software, regardless of the form and/or extent of the claim. By using the software you agree to this. The author further reserves the right to revise or alter the contents of this documentation or the ANSIPLUS software package from time to time without notifying any person or group of such changes or alterations. The Limited License and Disclaimer of Warranty shall be construed, interpreted and governed by the laws of the State of California. TRADEMARKS Microsoft and MS-DOS are registered trademarks of Microsoft Corporation. IBM and PS/2 are registered trademarks of IBM Corporation. Windows is a trademark of Microsoft Corporation. Other trademarked names may appear in this manual. The author states that he is using the trademarked names only for editorial purposes, and to the benefit of the trademark owner, with no intention of infringing upon any trademark. Table of Contents I. Introduction Product description . . . . . . . . . . . . . . . . . . . . . 1 Registration . . . . . . . . . . . . . . . . . . . . . . . . 2 Limited License . . . . . . . . . . . . . . . . . . . . . . . 3 Technical Support . . . . . . . . . . . . . . . . . . . . . . 4 II. Features summary VGA/EGA display features . . . . . . . . . . . . . . . . . . 5 Integrated console functions . . . . . . . . . . . . . . . . 6 Other ANSIPLUS features . . . . . . . . . . . . . . . . . . . 7 III. Installing ANSIPLUS Installing the device driver and utility programs . . . . . . 10 Changing the ANSIPLUS startup configuration . . . . . . . . . 12 IV. Using ANSIPLUS Special keyboard functions . . . . . . . . . . . . . . . . . 18 Selecting and defining colors . . . . . . . . . . . . . . . . 19 Controlling other ANSIPLUS features . . . . . . . . . . . . . 23 Editing ANSI escape sequence programs and files . . . . . . . 26 V. ANSIPLUS escape sequences Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 27 VI. Technical notes ANSIPLUS and Windows 3 . . . . . . . . . . . . . . . . . . . 29 ANSIPLUS extensions and the ANSI standard . . . . . . . . . . 30 Escape sequence recognizer enhancements . . . . . . . . . . . 30 Direct access to video RAM vs. BIOS calls . . . . . . . . . . 31 Installation checks . . . . . . . . . . . . . . . . . . . . . 31 Hooked interrupts . . . . . . . . . . . . . . . . . . . . . . 32 I. INTRODUCTION The DOS console device driver provides the critical interface between you and your personal computer. It controls the output you see from DOS and accepts your keyboard input, and you spend a whole lot of time using it. Unfortunately, the standard CON and ANSI device drivers supplied with DOS do not take full advantage of the capabilities of the major video controllers currently in use: VGA and EGA. In addition, the standard personal computer BIOS has limitations that have had to be addressed individually by several TSR programs or device drivers, by work-arounds and special drivers in major application programs, or by development of graphic user interfaces such as Windows. The ANSIPLUS console device driver integrates major console elements missing from DOS and the personal computer BIOS into a single compact device driver that can easily be controlled and personalized. With ANSIPLUS installed: * User interaction with the DOS command shell and many applications will be significantly improved. * Screen output will be faster than with DOS's ANSI and non-ANSI drivers. * The user will have complete control over colors and VGA/EGA capabilities. * Users of Windows 3 will have access to ANSIPLUS features in all windowed and full screen DOS sessions. * The user will also benefit from all the other display and keyboard features provided by ANSIPLUS. This is a fully functional Shareware copy of the ANSIPLUS product. As such, it is made available to the general computing public for evaluation. Users are licensed to operate ANSIPLUS on their personal computers for the purpose of test and evaluation for a limited trial period of thirty days. After evaluation, if the user decides the ANSIPLUS programs are not of sufficient merit to warrant purchase through registration with Kristofer Sweger, all ANSIPLUS programs should be removed from their personal computer. If ANSIPLUS is found to be useful and is in regular use, then registration is required. This manual is organized in six chapters: * Chapter 1 introduces ANSIPLUS and covers product licensing and support; * Chapter 2 summarizes ANSIPLUS features for those who want to know what it can do; * Chapter 3 discusses installing and configuring ANSIPLUS on your computer; * Chapter 4 describes keyboard functions and utility programs accessible to users after installation; * Chapter 5 lists ANSIPLUS escape sequences; and * Chapter 6 contains several technical notes of interest to programmers and others. 1 REGISTRATION By paying the registration fee for ANSIPLUS, registered users are granted a license to use the software on any single computer system. Site licenses for use of ANSIPLUS on multiple computers are available upon request at a substantially reduced fee per machine. Registered users also receive: * A registered copy of the most recent version of ANSIPLUS. Registered copies of ANSIPLUS don't have that pesky time delay in the sign-on message. The registered version is also NOT Shareware, so it may not be copied for others. * A printed copy of the ANSIPLUS manual, which contains detailed documentation on using the ANSIPLUS Escape sequences. This information is provided only in the printed manual, and is not included in either the Shareware version or on the Registered diskettes. Registration helps support further improvements to ANSIPLUS. The easiest way to register ANSIPLUS is to print out the registration form file, REGISTER.pls, fill it out, and mail it with a check or money order to: Kristofer Sweger P.O. Box 378 Larkspur, CA 94977 Be sure to specify whether you want a 5.25" or 3.5" diskette, and to include the mailing address for your registered ANSIPLUS and manual. Pricing is shown in REGISTER.pls. California residents must also add sales tax. 2 LIMITED LICENSE Non-registered users of ANSIPLUS are licensed ONLY to evaluate the programs and device driver for up to thirty days for the sole purpose of determining whether or not it meets their requirements. All other use requires registration. Any other use of non-registered copies of ANSIPLUS by any person, business, corporation, or government organization, is not permitted. Registered copies of ANSIPLUS may NOT be copied for others. However, permission is hereby granted for individuals to copy the non-registered ANSIPLUS package for their own use (for evaluation and backup purposes) or for other individuals to evaluate, provided all of the following conditions are met: * The ANSIPLUS package, including all related program and documentation files, cannot be modified in any way and must be distributed in its entirety, with no additions. The following computer files constitute the ANSIPLUS Shareware package: ANSIPLUS.sys ANSIPLUS console device driver ANSIPLUS.doc ANSIPLUS Shareware documentation SETCOLOR.exe Color control utility program SETAPLUS.exe Driver features control utility program ANSICOM.exe ANSI escape sequence editor NEWAPLUS.exe ANSIPLUS bootup configuration program APLUSLIB.exe Execution library for the utility programs SETCOLOR.sch Color schemes file for SETCOLOR.exe CONSETUP.com Sample escape sequence program PUSHVID.com Save current video mode, video page and colors POPVID.com Restore saved video mode, page and colors INSTALL.exe Installation program INSTALL.inf Installation control file REGISTER.pls ANSIPLUS registration form README.pls Release notes * No price or other compensation may be charged for the ANSIPLUS package. A distribution cost may be charged for the cost of the diskette, shipping and handling, as long as the total per disk does not exceed US $6.00 in the U.S. and Canada, or US $10.00 internationally. * The ANSIPLUS package cannot be bundled or included with other goods or services, nor can it be included in any commercial software packaging offer, nor can it be "rented" or "leased" to others, without specific prior written agreement from Kristofer Sweger. All rights not expressly granted here are reserved to Kristofer Sweger. 3 TECHNICAL SUPPORT We want our users to be satisfied, and we find the interaction with real users of ANSIPLUS to be of great value. Many ANSIPLUS features are the result of user input. If you have a problem evaluating ANSIPLUS or want to make a suggestion, comment, or complaint, please contact us immediately. We can be reached by mail at P.O. Box 378, Larkspur, CA 94977, or by telephone at 415/924-5407. The ANSIPLUS technical support telephone line (415/924-5407) can be called weekdays from 10:00 AM to 5:00 PM, Pacific Time. We ask that you recognize that this service can easily be overwhelmed by calls with questions that are already answered in the documentation provided. When you do call, please try to have all your questions (and any necessary supporting data) ready so that we can deal with them efficiently in one short session. If you are reporting a software problem, we will need specific information about your computer system and how to recreate the problem. 4 II. FEATURES SUMMARY Although many of the ANSIPLUS features described here may seem technical, each meets a need, and they all cooperate as parts of one compact console device driver. In this chapter, they have been collected into three major groups: VGA/EGA display features, integrated console functions, and other ANSIPLUS features. The remaining chapters give details regarding specific features. VGA/EGA DISPLAY FEATURES The ANSIPLUS enhanced DOS console device driver is tailored to take advantage of VGA and EGA display capabilities: Mode recognition For any VGA/EGA display mode, the driver can properly address the entire screen. ANSIPLUS automatically recognizes and adapts to various VGA or EGA screen modes, both text and graphics, including extended modes with large numbers of lines and/or columns. ANSIPLUS can also automatically adapt to and compensate for older video controllers with very limited numbers of colors or shades (i.e., CGA or monochrome boards). Speed In text and in 16-color VGA/EGA graphics display modes, the driver bypasses the ROM BIOS and goes straight to the video RAM, so it can operate much faster than either the original DOS console driver or the DOS ANSI driver. Programs that write large character strings to the standard output (console) file handle in "raw" mode can generate their output many times faster. Color selection ANSIPLUS provides full control over colors. In color text modes, sixteen foreground and background colors are supported. In 16-color VGA/EGA graphics modes, ANSIPLUS allows mixing of background colors, for a total of 136 possible background colors. In 256-color VGA graphics modes, all 256 foreground and background colors are supported. Palette control Control over VGA/EGA palette registers and VGA DAC registers allows selecting and maintaining colors using the video controller's full capabilities. The driver traps all video mode changes, and installs the palette and/or DAC colors of the user's, or of ANSIPLUS's color scheme. Applications that set their own palettes will continue to do so, but those that do not can now use custom color choices. Blinking can also be kept disabled to allow 16 background colors in text modes. Text size ANSIPLUS allows selection of alternate VGA/EGA character sets, giving control over the character height, and thus the number of text lines used in any VGA/EGA video mode. Smooth scrolling ANSIPLUS supports smooth scrolling of the screen (for fast CPUs with 16-bit VGA/EGA), so the screen can be read while it is moving. Options are provided to control the use and rate of smooth scrolling. 5 Extended modes The ANSI Set Mode control sequence has been expanded to allow specifying VGA/EGA modes that are based on full AX and/or BX CPU register values, extending ANSI-type control to Super VGA/EGA controllers that require such register settings. Super VGA controllers that conform to the VESA standard are also automatically recognized, and VESA extended set mode calls are made by the ANSIPLUS driver for modes of 100h or higher. INTEGRATED CONSOLE FUNCTIONS The ANSIPLUS driver efficiently integrates several useful console functions that in the past had to be provided by separate TSR programs or device drivers: Screen saver A screen saver blanks the VGA/EGA screen after several minutes of screen, keyboard and mouse inactivity. The screen can be brought back by any keystroke (including shift keys) or by mouse movement or buttons. The screen saver feature can be enabled or disabled by the user, and is automatically disabled in certain situations. Keyboard buffer As many PC users eventually discover, the standard personal computer BIOS provides a keyboard input type-ahead buffer of only 15 characters, which is enough for only the shortest of commands. ANSIPLUS extends this by 113 keystrokes for a total type-ahead of 128 keystrokes (configurable for more if necessary). Repeated keys Another problem with the standard BIOS keystroke buffer occurs when keys are held down too long, and the buffer rapidly fills with repeated (or "typeamatic") keys, which are then processed long after the key is lifted. Spreadsheet users often experience this when holding down one of the arrow keys. ANSIPLUS disables repeat key type-ahead, but does allow repeat keys that are immediately consumed by programs, so the type-ahead buffer cannot be filled with unintended keystrokes. Repeated digits are also suppressed, making it impossible to inaccurately enter a number just because a key is held down too long. Scroll-back Every DOS user sooner or later needs to recall something that was on the screen, but has scrolled off the top. Programmers often encounter this with error messages, and other users with file directory listings. To address this problem, ANSIPLUS supports screen scroll-back: all lines scrolled and cleared from the screen in text modes are captured by the ANSIPLUS driver so that the user can stop at any time and browse through recent screen contents. Scroll lock Large directory listings and other rapidly generated screen output can often fly by on the screen too fast to be read. Hitting the Scroll Lock key will freeze the screen when ANSIPLUS or the BIOS next tries to scroll it. When the screen is frozen, several keystroke options allow control over subsequent screen output. 6 Beep tone The standard personal computer BIOS Control-G beep tone generator waits in a programmed loop until sound output is completed. Sometimes, error or other conditions detected in a running program can generate a rapid sequence of beeps, and the computer will just hang for what seems an eternity, beeping away. ANSIPLUS has an interrupt-controlled tone generator that lets the beep tone be finished in parallel with subsequent processing. Multiple beeps are ignored if a tone is currently being generated, so programs cannot be slowed down by a rapid series of beeps. Options are provided for defining the tone and using or not using the tone generator. OTHER ANSIPLUS FEATURES Other ANSIPLUS features include: User control Menu driven utilities give the user full control over selected colors, color palettes, border colors, video modes, text height, key reassignment, beep tone definition, driver table sizes, and all other configurable features. Loading options At load time, the ANSIPLUS driver can divide itself into sharable code (about 14k) and unshared code/data (about 3.5k) sections, placing the shared code in either XMS upper memory blocks (from 640K to 1M) or in high memory (1M to 1M+64K) along with DOS 5.0, and leaving only the unshared part in low memory. Bright key echo ANSIPLUS highlights user-typed keys when they are displayed by DOS on the screen, giving a clear visual separation of typed entries from computer output. If unwanted, this feature can be disabled. ANSI support All DOS ANSI.sys escape sequences are supported, plus additional ANSI/VT-100 escape sequences for clearing the screen, erasing lines, inserting and deleting lines, and inserting and deleting characters. Mono/CGA support ANSIPLUS should give reasonable and readable displays in all display modes, including those with a very limited number of colors or shades. ANSI-type programs written in terms of 16 colors will be executable on machines with simpler video capabilities, if ANSIPLUS is running on that machine. 7 Key processing ANSIPLUS includes several special key processing options: (1) the shift-alphabetic keys can cause Caps-Lock to unlock, much like a typewriter releases its shift lock whenever a shift key is pressed; (2) the Enter key can restore Caps-Lock after it was unlocked by a shift-alphabetic key, thus restoring Caps on completion of an "entry"; (3) Control-C can cause a Control-Break, for those users who prefer the Control-C key; and (4) the DOS "Non-Destructive" input function can return the last key in the keyboard buffer instead of the first, so that it always reflects what has last been typed. Line wrapping When the length of a line displayed on the screen exactly equals the width of the screen, the standard DOS console device drivers cause a blank line to be output. ANSIPLUS suppresses output of these unintended blank lines. Graphics cursor The DOS console drivers do not show a cursor on the screen when in graphics modes. ANSIPLUS can display a cursor when keyed entries are requested by DOS in a graphics mode. BIOS TTY ANSI ANSIPLUS provides an option to trap and execute ANSI control sequences in BIOS Int 10h Write TTY output as well as in DOS standard console output. Transparent mode On occasion, it is undesirable to have the ANSI driver fill in the background color of each character space as it writes characters. ANSIPLUS includes a "transparent" background mode that will write each output character in the current foreground color over whatever background is currently at the cursor position. Text treatments In 16-color graphics modes, ANSIPLUS can apply bold, underline, black shadow, slant (italics), or black outline text treatments, in any combination, to output characters for emphasis or improved legibility. Esc pass-through Unlike the ANSI.sys driver, the Esc character is trapped by ANSIPLUS only when followed by a left bracket ("["), so programs that write Esc (a left arrow) to the screen will continue to do so after ANSIPLUS is installed. VGA mono emulation Because application developers with VGA color monitors sometimes need to see how their systems will look when run with a monochrome VGA monitor, ANSIPLUS provides an option to emulate a monochrome VGA monitor on a color monitor. 8 Status reporting To allow programs to query ANSIPLUS about more than just the current cursor location, the device status report has been extended to report information about the current video mode, video page, numbers of rows, columns and colors, current or default definition of colors, and more. Installation checks To facilitate developing applications that can use ANSIPLUS features, ANSIPLUS responds to standard Int 2Fh ANSI.sys installation checks, and includes extensions that can distinguish ANSIPLUS from ANSI.sys. 9 III. INSTALLING ANSIPLUS INSTALLING THE ANSIPLUS DEVICE DRIVER AND UTILITY PROGRAMS The ANSIPLUS package includes an installation and configuration program called INSTALL.exe, which should properly handle most installations. INSTALL analyzes the runtime environment and CONFIG.sys of the target drive, locates the source files, copies ANSIPLUS to the target drive (or to any sub-directories of the user's choice), and updates CONFIG.sys. For those who are not content to use default driver settings, the configuration section of the INSTALL program then lets the user set the startup (boot) driver table sizes, colors, and feature settings, as well as high memory loading options that affect CONFIG.sys. These configurations can be performed either at installation time, or any time later on an installed drive by using the NEWAPLUS.exe program. Context sensitive help (via the F1 key) is provided for all entries. Startup configuration changes are described in the following section, starting on page 12. The INSTALL program gives an opportunity (via the Installation menu) to set the destination directory for each installed file or for classes of files. If the directory is not specified for a file, the following assumptions will apply: * If an ANSIPLUS file name matches the name of a file in the default directory, root directory, or on the system PATH of the destination drive, then the ANSIPLUS file will be copied over the matched file (i.e., updated). This is intended to make installation of ANSIPLUS updates a snap. * New files are added to a directory for each class of file (i.e., driver, utility program, or documentation/other). If any file in the class is being updated, then the class directory will be the same as the updated files. Otherwise, the class directory will be "\ANSIPLUS". It is recommended that you put all of the ANSIPLUS utility programs (SETCOLOR, SETAPLUS, ANSICOM, NEWAPLUS and APLUSLIB) on your system PATH so that they can be used easily. It is critical that the execution library, APLUSLIB.exe, be located either in the same directory as the other utility programs or on the system PATH. If it is not, the utility programs will not run! You may also want to place the ANSIPLUS.sys device driver in the root directory. Before installing ANSIPLUS, or any other new device driver, be sure you have a bootable floppy disk as insurance against trouble getting your system to run after the device driver is installed. 10 The following three examples illustrate using INSTALL to install ANSIPLUS: * If you received ANSIPLUS on a floppy disk and want to install it on your hard disk, use the following installation procedure: (1) Set the default directory to the hard disk (i.e., get a C> prompt). (2) Insert the ANSIPLUS diskette in drive A: (or other floppy drive). (3) Enter the following command: A:INSTALL * If you received ANSIPLUS as a ZIP file, use the following procedure: (1) Create a sub-directory on the hard disk to contain the unzipped ANSIPLUS files. Move ANSIPLUS.zip to this directory and make it be the default directory. (2) Unzip the files into the directory with the command: PKUNZIP ANSIPLUS (3) Then enter the command: INSTALL * To install ANSIPLUS on bootable disk B:, from hard disk directory C:\APLUS, enter the command: C:\APLUS\INSTALL B: 11 CHANGING THE ANSIPLUS STARTUP CONFIGURATION Changes to the startup configuration for ANSIPLUS are made with the NEWAPLUS.exe program. (INSTALL also lets you make these changes, but INSTALL.exe is actually a tiny program that calls NEWAPLUS.exe to perform the installation.) You run NEWAPLUS with a command of the form: NEWAPLUS <target> where <target> is the drive letter for a bootable diskette or hard disk partition with ANSIPLUS installed. If <target> is omitted, the current default drive will be used or, if it isn't bootable, the drive referred to by the COMSPEC system environment variable. After NEWAPLUS confirms that the target disk contains ANSIPLUS, you are presented with a startup configuration menu that has nine revision option groups: Initial Colors * Color selection sub-menus let you choose from the current 16-color palette the screen colors that will be used for text foreground and background when the system starts up. ANSIPLUS maintains two sets of foreground and background colors: those that are currently on the screen, and "default" colors to be applied when an ANSI Set Graphics Rendition reset (i.e., Esc [0m) is detected. The startup selections for both color combinations can be controlled from this sub-menu. Palette Definition * The color palette determines the precise colors you will see in 16 color video modes. ANSIPLUS maintains two palettes: the current palette on the screen, and a default palette that is loaded when ANSIPLUS first starts and whenever the video display mode is changed. All changes you make using the NEWAPLUS color palette option will apply to the default palette. Border Color * The border color is generated for the "overscan" region on the outside edges of the screen. You can select any available color as the default border color, which will be installed when ANSIPLUS starts up and whenever the display mode is set. 12 Loading Option ANSIPLUS can be loaded into memory up to four different ways, depending on your computer's capabilities and what is contained in CONFIG.sys: * ANSIPLUS can be loaded into low memory below 640K. This is the default. * ANSIPLUS can load itself into upper memory blocks. At load time, the driver can divide itself into two sections: sharable code totaling about 14k, and unsharable code/data totaling about 3.5k. The shared code can be placed in either XMS upper memory blocks (from 640K to 1M) or in high memory (1M to 1M+64K) along with DOS 5.0, leaving only the unsharable 3.5k in low memory. Because all ANSIPLUS driver data remains in low memory as part of the DOS CON driver, it will be localized under Windows 3.0. Under DOS 5.0, this option should work whether DOS=UMB appears in CONFIG.sys or not. The following CONFIG.sys command loads ANSIPLUS into the XMS upper memory blocks: DEVICE=ANSIPLUS.sys /U * Under DOS 5.0, with the DOS=HIGH line in CONFIG.sys, ANSIPLUS can load itself into high memory addressed just above 1 megabyte. This area contains 64k, but DOS may require only about half of it, leaving the remainder either unused or allocated to disk buffers or other tables. ANSIPLUS can load itself into this area and share the space with DOS. However, when this is done, certain (antique) programs that assume memory addresses over one megabyte will "wrap around" to addresses starting at zero may not operate correctly. If you experience any problems, load ANSIPLUS into XMS upper memory blocks instead. The following CONFIG.sys command will load ANSIPLUS into the DOS 5.0 high memory area: DEVICE=ANSIPLUS.sys /H * ANSIPLUS can be loaded high by DEVICEHIGH or equivalent. Users of Windows 3.0 and EMM386, QEMM, or DOS 5.0 should note: With DOS 5.0 (using DEVICEHIGH and EMM386), or with other XMS drivers such as QEMM (using LOADHI), ANSIPLUS can be loaded into upper memory blocks above 640k to provide a 17k larger program area below 640k. However, if Windows 3.0 will be run in 386 Enhanced mode, it is strongly recommended that ANSIPLUS (or any other ANSI driver) not be loaded into high memory by these methods. This is because Windows 3.0 does not localize the XMS upper memory block area above 640k for its virtual 8086's, and so only one global copy of ANSIPLUS would be shared among all virtual machines. This can cause trouble: if, for example, a program in one window selects colors, then those colors would also be in force for all DOS programs in other windows! This localization problem appears to have been fixed in Windows 3.1. 13 Color Control * The ANSIPLUS driver ordinarily traps all video mode changes and installs the palette and/or DAC colors of the user's, or of ANSIPLUS's default color scheme. Applications that set their own palettes will continue to do so, but those that do not will use the installed color choices. If this feature is disabled, the VGA/EGA controller manufacturer's colors will be loaded when the video mode changes. * In color text modes, the VGA and EGA allow either sixteen background colors with no blinking foreground text, or eight background colors with foreground text that may or may not blink. In monochrome text mode 07h, when blinking is disabled there are three backgrounds possible: black, gray or white, and with blinking enabled there are two: black and gray. If blinking is disabled, ANSIPLUS will display sixteen (or three) background colors, and when it is enabled, you will see only eight (or two) background colors. * ANSIPLUS highlights user-typed keys when they are displayed on the screen, giving a clear visual separation of typed entries from computer output. Over dark backgrounds, the key is shown in white, and over light backgrounds it is shown in black. If this feature is not wanted, it can be disabled. * Because application developers with VGA color monitors sometimes need to see how their systems will look when run with a VGA monochrome monitor, ANSIPLUS provides emulation of monochrome monitor VGA on a color monitor. In normal operation, this feature should be disabled. Display Control * The ANSIPLUS screen saver blanks the VGA/EGA screen after several minutes of screen, keyboard and mouse inactivity. The screen is brought back by any keystroke, including shift keys, or, if a mouse is connected, by moving it or pressing a button. The screen saver is automatically disabled under Windows and when certain games or other programs that take over the timer are running, and does not interfere with any known programs. However, if this feature is not desired, it can be turned off. * The time of inactivity before the screen goes blank is configurable between one and twenty minutes. * During periods of keyboard inactivity, ANSIPLUS's screen saver uses MS mouse Int 33h calls to test the status of the mouse. In the unlikely event these calls interfere with the mouse driver, they can be disabled. * On the IBM PS/2, the mouse is usually connected to the pointing device port, and mouse activity will cause interrupts on the Mouse Event interrupt number 74h, so ANSIPLUS monitors this interrupt to unblank the screen. If the screen fails to go blank after a long idle period, or if this interrupt is used for another purpose, this feature should be disabled. * The DOS console drivers do not show a cursor on the screen when using a graphics mode. ANSIPLUS displays a pseudo-cursor when keyed entries are requested by DOS in a graphics mode. If this feature interferes with the appearance of a graphics mode program, it can be disabled. 14 * Programs that write screen output using ROM BIOS Int 10h Function 14 (Write TTY) ordinarily cannot use ANSI Escape sequences for screen control. ANSIPLUS includes a feature to allow this. * When the VGA/EGA video controller does not allow setting a palette register unless a vertical retrace is in progress, or when "snow" or other problems occur during palette color changes, ANSIPLUS provides an option to wait for a vertical retrace whenever setting a palette register. Otherwise, this feature should remain disabled. * ANSIPLUS contains an internal stack for saving and restoring video context information (rows and columns, colors, display modes, etc.). The default size allows 25 pushes, but this can be configured to a larger value if needed. Screen Scrolling * ANSIPLUS uses the Scroll-Lock key as a hot key for freezing fast screen output and for activating screen scroll-back. If these features are not desired, or to run those few applications that use Scroll-Lock for other purposes, the ANSIPLUS Scroll-Lock key can be disabled. However, before you completely disable ANSIPLUS's Scroll-Lock key, try the Alt-Scroll-Lock combination instead (see next option). * An alternative hot key is Alt-Scroll-Lock. If this key is enabled, the Alt key must be pressed simultaneously with the Scroll-Lock key to cause the ANSIPLUS Scroll-Lock function to be activated. If it is disabled, the Scroll-Lock key will function with or without any other simultaneous key. * As lines are scrolled off the top of the screen, the ANSIPLUS driver can save them for later viewing. This viewing is called screen scroll-back. Most of the time this is a very useful and unobtrusive feature, but if it is undesired, or if storage of the saved lines in unused portions of the video RAM is found to interfere with something, it can be disabled. * On most computers, screen scroll-back should operate correctly under Windows. However, a few (buggy) video drivers for Windows 3.0 do not provide a full 32k of text RAM to DOS applications running in a window, and this can be disastrous when ANSIPLUS tries to save or view lines for scroll-back. Because of this, the default setting for scroll-back under Windows is to be disabled. If you run all DOS applications full screen, or if Windows and scrolling-back in a window work correctly in an experiment on your system, this feature should be enabled. * ANSIPLUS captures for scroll-back all standard DOS output that is scrolled off the top of the screen or cleared from the screen. An option is provided to capture full lines scrolled off the top by BIOS calls, as well as screens not containing DOS output, when they are cleared by BIOS call. * Every time that video page 0 (the normal video page for all DOS output) is cleared, the first through last non-blank lines on the screen (plus one above and below) are captured for scroll-back. When the second and higher video pages are cleared, they will not be saved unless lines have been scrolled off the top. An option is provided to capture the higher video pages too when they are cleared. 15 * ANSIPLUS stores captured screen lines in unused parts of the video RAM, with usage based on whether a display page has ever been selected for display. Virtually all text mode applications select a page before filling it with text, so ANSIPLUS should generally know what is used and what isn't. However, if an application fills the second or a higher video page with text before that page has ever been selected, ANSIPLUS will clear it when it is selected. This option may fix such a problem by protecting the second video display page from scroll-back storage, but maximum capacity for scroll-back will be reduced by one page. * Smooth scrolling can gradually move the entire screen's text up so it can be read while it moves. This feature can also be toggled on and off by the Shift-Scroll Lock key combination. Smooth scrolling will appear unacceptably choppy on computers with lower powered CPUs and/or video controllers that cannot move a full screen of text in the video RAM completely during a vertical retrace. If this occurs, the feature should not be used. * Smooth scrolling can be disabled under Windows. If smooth scrolling does not perform well in full screen DOS sessions under Windows, or if there are other problems, then this should be done. * Because it takes time to smoothly scroll the screen, smooth scrolling of large amounts of screen output can significantly delay the computer. An option is provided to increase the scrolling rate when the smooth scrolling operation is taking a significant proportion of the computer's time. This can help, for example, to prevent data overruns when smooth scrolling is used with a communications program that scrolls the entire screen. Keyboard * By default, ANSIPLUS increases the keyboard buffer capacity to 128 characters, which should hold at least as much as most users can type ahead accurately. To expand the computer's keyboard buffer capacity, an extension buffer is retained within ANSIPLUS, and whenever the ROM BIOS buffer has space available for keys held in the ANSIPLUS buffer, they are moved into the standard ROM BIOS buffer. You configure this buffer by specifying the total number of keys to be buffered. * ANSIPLUS has the ability to translate single keystrokes to full commands or other pre-determined key sequences. This feature is called key reassignment, and it can be enabled or disabled without affecting the contents of the key reassignment tables stored within the ANSIPLUS device driver. * The space allocated for storing ANSI keystroke reassignments may also be configured. Each key reassignment requires approximately four bytes plus the length of the reassignment. You configure the total table size in bytes. * Normally, the Caps Lock key locks the alphabetic keys in upper case, and when a shift key is held down, letters are entered in lower case. This continues until Caps Lock is pressed again to unlock the Caps, and can often be confusing if you forget that Caps were locked. ANSIPLUS has an option to have shift-alphabetic keys cause the Caps to unlock, much like a typewriter releases its shift lock whenever a shift key is pressed. 16 * In many cases, when Caps Lock has been released by a shift-alphabetic key combination, mixed upper and lower case characters are needed for only a single entry, and Caps Lock should be reinstated thereafter. ANIPLUS includes an option to turn Caps Lock back on again when the Enter key is pressed after Caps were unlocked by a shift-alphabetic key, thus restoring Caps Lock on completion of an "entry." * For those users who find it more convenient to break out of programs with the Control-C key combination than with Control-Break, ANSIPLUS has an option to generate a keyboard break whenever Control-C is entered. * The "Non-Destructive" input function of DOS's BIOS reads an input key from the keyboard unofficially just to see what it is, allowing it to really be read later. This function is used to see what has been typed, and to read it or flush the keyboard buffer only if it matches some criterion (such as Escape or Control-C). Because the standard DOS keyboard driver always looks at the first key in the buffer, if it doesn't meet the criterion, no matter what is typed later will not be checked. ANSIPLUS gets around this with an option to return the last key from the buffer instead of the first. Tone Definition * The ANSIPLUS driver includes a timer-interrupt controlled Control-G beep tone generator that lets the beep tone be finished in parallel with subsequent processing. Multiple beeps are ignored if a tone is currently being output, so programs cannot be slowed down by a rapid series of beeps. The tone generator is used for both standard DOS console output and BIOS Int 10h Write TTY calls. If the tone generator is disabled, the original DOS beep tone will be used. * When Windows 3 is running in 386 mode, and a DOS program running in the background outputs a Control-G, the background program's virtual 8086 may not be running fast enough to accurately time the tone. Because of this, the tone can drag out and sound strange. Disabling ANSIPLUS tone generation under Windows restores the original Windows sound driver, but makes the tone frequency and duration non-configurable. * The beep tone definition is stored in a table in the ANSIPLUS driver that requires four bytes per frequency and duration. You can configure the size of this table by specifying the maximum number of notes allowed in the beep. 17 IV. USING ANSIPLUS This chapter describes your controls over ANSIPLUS when it is running. Four subjects are covered: special keyboard functions; selecting and defining colors with the SETCOLOR.exe utility program; controlling other ANSIPLUS features with the SETAPLUS.exe utility program; and creating and editing ANSI-type escape sequence programs and files with the ANSICOM.exe program. SPECIAL KEYBOARD FUNCTIONS ANSIPLUS uses special keyboard control to implement its scrolling functions. To activate these, the Scroll-Lock (or Alt and Scroll-Lock) key is used as a hot key toggle: Scroll-Lock enables or disables screen scroll freezing and scroll-back Shift-Scroll-Lock enables or disables smooth scrolling When your Scroll-Lock toggle is recognized by the computer, you will hear a short tone. When the screen is frozen by Scroll-Lock, (as indicated by the light on enhanced keyboards), normal key input is disabled and the following keys apply: Home Go to the top of the lines saved for scroll-back PageUp Scroll up one page Shift Scroll up one-half page tab Up arrow Scroll up one line End Go to the bottom (i.e., the original screen display) PageDn Scroll down one page Tab Scroll down one-half page Down arrow Scroll down one line Insert Save the current screen page for later scroll-back Left View a lower numbered display page arrow Right View a higher numbered display page arrow Escape Cancel scroll lock, return to normal key processing Scroll lock Cancel scroll lock, return to normal key processing If you try to exceed the limit of travel up, down, left or right, a short low pitched tone will sound. If you enter any key other than those above, you will hear a short warbling sound, Scroll Lock will be canceled, the screen will return to its normal display, and the key will be passed back to the running program. If the screen was frozen during output, the PageDn, Tab and Down arrow keys will allow one page, one-half page, and one line of additional output, respectively, before freezing the screen again. Pressing a shift key will release the screen as long as the key is held down. 18 SELECTING AND DEFINING COLORS The SETCOLOR.exe utility program provides extensive control over colors for your running system. With this program, the user can view the current colors, select colors for use, create and apply named color schemes, edit the color palette, set the border color, and save and load color definitions. SETCOLOR.exe is executed by a command of the form: SETCOLOR <keyword> [<keyword> ...] where each <keyword> selects a foreground or background color or other option. If no <keyword> is supplied, you are presented with a menu of choices: * Color selection submenus let you choose from the current 16-color palette the screen colors that will be used for text foreground and background. ANSIPLUS maintains two sets of foreground and background colors: those that are currently on the screen, and default colors to be applied when an ANSI Set Graphics Rendition reset (i.e., Esc [0m) is detected. You can control both color combinations from this sub-menu. * The color palette determines the precise colors you will see in 16 color video modes. ANSIPLUS maintains two palettes: the current palette on the screen, and a default palette that is loaded when ANSIPLUS first starts and whenever the video display mode is changed. You can control both palettes using this option, but unless you specifically set the default for each color you redefine, your colors will only apply until the next display mode change. * The border color is generated for the "overscan" region on the outside edges of the screen. Again, ANSIPLUS maintains both a current border color and a default border color. You can select any available color as border color, and can control both the current and default borders with this option. As for palette changes, unless you specifically set the default border color, your border color will apply only until the next display mode change. From the command line, colors may be selected by name or code number, where codes 0-15 identify the 16 palette colors, 128-143 select foreground colors, and 192-207 select background colors. The relationship between color names and code numbers is depicted in Table 4-1: 19 +--------------------------------------------------------+ | Table 4-1 | | Color Names and Codes | +-------------------+--------+--------------+------------+ | | Color | Foreground | Background | | Color Name | Code | Code | Code | +-------------------+--------+--------------+------------+ | | | | | | BLACK | 0 | 128 | 192 | | DKGRAY | 8 | 136 | 200 | | GRAY | 7 | 135 | 199 | | WHITE | 15 | 143 | 207 | | RED | 9 | 137 | 201 | | DKRED | 1 | 129 | 193 | | BROWN | 3 | 131 | 195 | | YELLOW | 11 | 139 | 203 | | GREEN | 2 | 130 | 194 | | LTGREEN | 10 | 138 | 202 | | CYAN | 6 | 134 | 198 | | LTCYAN | 14 | 142 | 206 | | BLUE | 4 | 132 | 196 | | LTBLUE | 12 | 140 | 204 | | MAGENTA or PURPLE | 5 | 133 | 197 | | LTMAGENTA or PINK | 13 | 141 | 205 | +-------------------+--------+--------------+------------+ In 256 color modes, you may also use 256-511 to select the foreground, 512-767 to select the background, or 0-255 after the BORDER keyword to select the border color. Several modifying keywords can assist the color selection: DARK, DIM or NORMAL for low intensity colors, LIGHT, BRIGHT or INTENSE for high intensity colors, FOREGROUND or FGD for foreground following, BACKGROUND, BGD, or ON for background following, REVERSE to swap the current foreground and background, BORDER for border color selection following, or DEFAULT to select the current colors as the default colors. If named colors or color codes 0-15 are specified without the foreground or background keywords, then the first color is assumed to be the foreground and the second the background. Keywords may also be shortened; the first partial match will be used. Several examples may help to clarify these rules: SETCOLOR bgd blue sets the background to dark blue SETCOLOR light cyan blue default default colors are light cyan foreground and blue background SETCOLOR 7,0 gray foreground, black background SETCOLOR bright green on blue high intensity green foreground, dark blue background SETCOLOR border cyan set the border color to cyan SETCOLOR reverse reverses the current foreground and background colors SETCOLOR rev reverses foreground and background 20 Any unmatched keywords are checked against user-defined color schemes in a file named SETCOLOR.sch. This editable ASCII text file, which should be placed in the same directory as the SETCOLOR.exe program, contains any number of named color schemes of the user's choice. User supplied color schemes are entered into the file with a text editor, with each line entered in the form: <name> = <keyword> [<keyword> ...] where <name> is the name of the user supplied color scheme, and <keyword> is any valid SETCOLOR program keyword or other option. Table 4-2 shows the SETCOLOR.sch file included with ANSIPLUS as a sample. +---------------------------------------+ | Table 4-2 | | Sample Color Schemes File | +---------------------------------------+ | evening = light cyan blue border 17 | | night = light blue black border 17 | | dawn = yellow cyan border 35 | | daylight = light blue white border 17 | | sun = bright red yellow border 46 | | sky = blue light blue border 17 | | forest = black green border 24 | | earth = yellow brown border 38 | | regal = pink purple border 21 | | candycane = dark red pink border white| | bw = gray black border dkgray | +---------------------------------------+ A user color scheme may be specifically selected on the SETCOLOR command line by preceding its name with the keyword SCHEME, for example: SETCOLOR SCHEME JOE selects a color scheme named JOE The SETCOLOR program also includes keyword options to reset, edit, load and save the current color configuration. These include: RESET Install defaults as the current colors IBM or OEM Install the OEM VGA/EGA palette as the current colors PALETTE Edit the color definitions for the 16-color palette SAVEFILE <filename> Save the current 16-color definitions in a file SAVE256 <filename> Save the 256 VGA DAC color definitions in a file LOADFILE <filename> Load a color definition file SAVECURRENT <file> Save the 16 current colors as an executable program SAVEDEFAULT <file> Save the 16 default colors as an executable program SAVEPROGRAM <file> Save both the current and default colors as a program The SAVEFILE, SAVE256 and LOADFILE keywords generate and load color definition files. The color definition files created by SAVEFILE contain 36 lines: 32 lines define the red, green and blue intensities for colors 0 to 15, both current and default, and the other four define the current and default foreground, background and border colors. Files created by SAVE256 contain 512 lines: 256 for the default DACs and 256 for the current DACs. Table 4-3 is a sample of lines from a SAVEFILE color definition file. 21 +------------------------------+ | Table 4-3 | | Sample Color Definition File | +------------------------------+ | Default = 142,196 | | DBorder = 0,81,162 | | DColor 2 = 16,162,81 | | DColor 3 = 113,65,16 | | DColor 4 = 0,0,105 | | DColor 5 = 97,0,97 | | Current = 135,192 | | Border = 0,0,0 | | Color 2 = 0,170,0 | | Color 3 = 0,170,170 | | Color 4 = 0,0,170 | | Color 5 = 170,0,170 | +------------------------------+ Users are free to edit color definition files to create their own colors, to delete any lines from them, or to put the lines in any order except that all default color definitions must precede all current color definitions in the file. If no file name is given for a LOADFILE, SAVEFILE or SAVE256 request, the file name SETCOLOR.def in the current directory will be used. LOADFILE checks the system PATH for color definition files to be loaded, so any commonly used color files can reside in a directory on the PATH. The SAVECURRENT, SAVEDEFAULT, and SAVEPROGRAM keyword options create executable ".com" files that can be called later by name to install colors. These programs can also be edited by the ANSICOM.exe utility program. The SETCOLOR program also controls ANSIPLUS VGA monochrome monitor emulation. Two keywords enable or disable this feature: MONOCHROME begins VGA monochrome monitor emulation; and COLOR ends VGA monochrome monitor emulation and restores colors. And finally, SETCOLOR provides three reporting options: SHOW displays the 16 current colors in a band across the screen HELP gives a brief description of how to use the SETCOLOR program SCHEME HELP lists the available color schemes in file SETCOLOR.sch 22 CONTROLLING OTHER ANSIPLUS FEATURES The SETAPLUS.exe utility program is used to enable and disable various ANSIPLUS features while the system is running. It can also be used to set the video display mode, character height, video page and graphics mode text treatment options, to define or list key reassignments, or to define the Control-G beep tone. SETAPLUS.exe is executed by a command of the form: SETAPLUS <keyword> [<keyword> ...] where each <keyword> selects an ANSIPLUS feature or other option. As for the SETCOLOR.exe utility, if no <keyword> is supplied, you are presented with a menu of choices. These choices are shown in Table 4-4 below. +------------------------------------------------------------------------+ | Table 4-4 | | SETAPLUS Main Menu Options | +-----------+------------------------------------------------------------+ | Report | Display current ANSIPLUS optional feature settings | | Mode | Set the video display mode | | Height | Set the displayed character height | | Keyboard | Caps Lock, Ctrl-C and key read-ahead options | | Assign | Key reassignment enable/disable option and key definition | | Tone | Control-G beep tone generation options | | Color | Mode set color, blink, bright key echo and VGA mono options| | Display | Screen saver, graphics mode cursor and retrace wait options| | Scrolling | Scroll-Lock, scroll-back and smooth scrolling options | | Undo | Undo all feature changes since starting the main menu | | Quit | Quit and return to DOS | +-----------+------------------------------------------------------------+ From the SETAPLUS command line, you control each ANSIPLUS feature with its own selection keywords. These selectors are shown in Table 4-5 on page 24. When used in combination with the following keywords, each controllable feature can be enabled and disabled easily: ON, YES, or TRUE to enable the preceding feature, ENABLE to enable all following listed features, OFF, NO, or FALSE to disable the preceding feature, DISABLE to disable all following listed features, and RESET to set all features to their default values. The following examples illustrate use of the SETAPLUS command line to control ANSIPLUS features: SETAPLUS bright off Disable bright key echo SETAPLUS enable capsunlock saver Enable screen saver and Caps reset on Shift-alpha SETAPLUS reset Reset all features to their default status 23 +-------------------------------------------------------------------+ | Table 4-5 | | SETAPLUS Feature Selection Keywords | +------------+------------------------------------------------------+ | SETCOLORS | Install default (ANSIPLUS) colors on mode sets | | NOBLINK | Enable 16-color text mode background (disable blink) | | BRIGHT | Highlight echoed keys (bright key echo) | | MONOCHROME | VGA monochrome monitor emulation | | SAVER | Enable screen saver (blanker) | | MSMOUSE | Use MS mouse Int 33h polling in screen saver | | PS2MOUSE | Use PS/2 Int 74h mouse event interrupts in saver | | PSEUDOCURS | Generate pseudo-cursor in VGA/EGA graphics modes | | TTYTRAP | Trap ANSI escape sequences in BIOS Write TTY | | RETRACE | Wait for retrace before setting palette registers | | | | | CAPSUNLOCK | Unlock Caps Lock with shift/letter key combination | | CAPSRELOCK | Relock Caps with carriage return after shift/letter | | CTRLC | Generate Control-Break when Control-C is entered | | NDLAST | Read last key in buffer with non-destructive input | | KEYASSIGN | Enable ANSI key reassignment | | BEEP | Use ANSIPLUS Control-G beep tone generator | | WINBEEP | Allow ANSIPLUS beep tone under Windows | | | | | LOCK | Allow Scroll Lock key to freeze screen | | ALTLOCK | Require Alt-Scroll-Lock when freezing screen | | SCROLLBACK | Enable scroll-back of lines scrolled off top | | WINBACK | Allow scroll-back under Windows | | BIOSBACK | Capture lines scrolled by BIOS call | | CLSBACK | Capture erased pages never scrolled up | | PROTECT | Protect 2nd display page from scroll-back storage | | SMOOTH | Enable smooth scrolling | | WINSMOOTH | Allow smooth scrolling under Windows | | SPEEDUP | Speed up smooth scroll when delaying computer | +------------+------------------------------------------------------+ Other command line options include: MODE <decimal mode number> to set the video display mode, HEIGHT <height> to set the text character height, PAGE <page> to set the video page, KEYDEF to enter key reassignment definitions from the keyboard, KEYFILE <file name> to load key reassignment definitions from a file, LISTKEYS to list all current key reassignments, TONE <frequency, duration list> to set the Control-G beep tone, TEXT or TREATMENT to reset graphics mode text treatments, SHADOW, BOLD, ITALICS, UNDERLINE or OUTLINE to enable text treatments, STATUS to report the current video mode, number of colors, etc., FEATURES to report the settings of all ANSIPLUS features, REPORT to show both STATUS and FEATURES, and HELP to show all keyword options. 24 All the features controlled by SETAPLUS are described in Chapter 2 under Changing the ANSIPLUS Startup Configuration, starting on page 12, except for two: * Key reassignments can be created by SETAPLUS. You will be prompted for the key to reassign; after that, you type in the corresponding key reassignment, and terminate it with the End key. * The ANSIPLUS beep tone can be defined by SETAPLUS. To define the beep sound from the command line, use SETAPLUS and follow the keyword TONE with zero, one or more frequencies in Hertz and durations in milliseconds. For example, SETAPLUS TONE installs the default 880hz 385ms tone, and SETAPLUS TONE 1397,110,1047,165 defines a two-tone Control-G beep. To define the beep sound from the SETAPLUS main menu, select Tone Definition and run through the feature options. 25 EDITING ANSI ESCAPE SEQUENCE PROGRAMS After using ANSIPLUS for a while, the user will find it desirable to create short programs for frequently used video modes, color selections or definitions, key reassignments, etc. The ANSICOM.exe utility program provides this facility: with it, the user can create and edit small executable ".com" files or small printable text files that contain ANSI escape sequences. ANSICOM is executed with the following command: ANSICOM <filename> where <filename> is the name of the file to be edited. Your file to edit is selected using the following rules: * If no file name is supplied, you will be presented with a menu of ".com" files to select from. * If a file name is supplied, and it does not include a file type, a file type of ".com" is assumed. * When an existing ".com" file is edited, it is first checked for program code that outputs the ANSI escape sequences. If this is not found, ANSICOM will refuse to edit the file. * If the file to be edited is not a ".com" file, then it is assumed to be a non-executable printable text file. * If the named file is not found (including a search of the system PATH), ANSICOM will ask if a new file is to be created. Once the file has been properly identified, a full-screen editing display is presented, and you can go to work. Use the F1 key for context sensitive help. The ANSICOM full screen editing display automatically parses the user's entries and identifies the kinds of ANSIPLUS escape sequences entered, including incomplete escape sequences. ANSICOM will not allow the user to save a file containing an incomplete escape sequence. Beyond that, it is the user's responsibility to be sure that the escape sequences entered will do what he wants. 26 V. ANSIPLUS ESCAPE SEQUENCES This chapter lists and briefly describes each of the "ANSI" Escape sequences recognized by ANSIPLUS. They are described in detail in the printed ANSIPLUS manual. In the table, "#" represents any numeric parameter and "Esc" is the Escape character (decimal 27, hexadecimal 1Bh): Control Sequence Description ---------------- ----------- DISPLAY MODE AND CHARACTER SET Esc [#;#h Set video display mode Esc [#;#l Reset video display mode Esc [!#t Select character set height: 8, 14 or 16 scan lines Esc [!#;...;#e Select graphics mode text treatment options: bold, underline, slant, shadow, outline, or reverse Esc [!#v Select video page CURSOR POSITIONING Esc [#;#H Set cursor position Esc [#;#f Set cursor position Esc [#A Move cursor up Esc [#B Move cursor down Esc [#C Move cursor right Esc [#D Move cursor left Esc [#s Save cursor position, video mode, video page or colors Esc [#u Restore cursor position, video mode, page or colors COLOR SELECTION AND DEFINITION Esc [#;...;#m Select current color attributes for output characters Esc [!#;#;#;#;#c Define colors available, select palette, set up color blinking, restore color definitions or palette 27 Control Sequence Description ---------------- ----------- ERASE, INSERT AND DELETE Esc [#;#J Clear the screen Esc [#;#;#K Clear a line Esc [#;#L Insert lines on the screen or in a column range Esc [#;#M Delete lines from the screen or a column range Esc [#;#@ Insert characters on a line or a column range Esc [#;#P Delete characters from a line or a column range DRIVER STATUS AND CONTROL Esc [#;#n Query ANSIPLUS status: cursor position, current color selection, video mode and number of colors, screen and character dimensions, color definitions, feature settings, tone definition, key reassignment, etc. Esc [!#;...;#d Enable or disable ANSIPLUS driver feature settings Esc [!#;...;#g Define the Control-G beep tone Esc [#;...;#p Define key reassignment (also accepts quoted strings) Besides supporting all the escape sequences accepted by the MS-DOS ANSI.sys driver, ANSIPLUS accepts additional parameters for many, and includes several entirely new control functions. See Chapter VI, Technical Notes, for differences between ANSIPLUS and the ANSI.sys driver. 28 VI. TECHNICAL NOTES ANSIPLUS AND WINDOWS 3 Users of Windows 3.0 and 3.1 should consider using ANSIPLUS as well. The ANSIPLUS driver works well with DOS programs under Windows 3, and there are advantages to using it in Windows 386 Enhanced Mode. Because ANSIPLUS is a CON driver, local copies of it are included in each Windows 386 Enhanced Mode virtual 8086. This means that all the ANSIPLUS internal state variables, and those of its integrated console features, will be local to each virtual 8086, so there is no way they can interfere with each other. With DOS 5.0, or with an XMS driver such as QEMM (using LOADHI) or 386MAX, ANSIPLUS can be loaded into upper memory blocks above 640k to provide a slightly larger program area below 640k. However, if Windows 3.0 will be run in 386 Enhanced mode, it is strongly recommended that ANSIPLUS (or any other ANSI driver) not be loaded into high memory using these methods, and that ANSIPLUS load itself high instead. This is because Windows 3.0 does not localize the XMS upper memory block area above 640k for its virtual 8086's, and so only one global copy of ANSIPLUS would be shared among all virtual machines. This can cause trouble: if, for example, a program in one window selects colors, then those colors would also be in force for all DOS programs in other windows! This appaears to have been fixed in Windows 3.1. The ANSIPLUS driver detects when Windows 3.0 is running, and automatically disables the screen blanker. Disabling of three other features under Windows is user-configurable: * On most computers, screen scroll-back should operate correctly under Windows. However, a few (buggy) video drivers for Windows 3.0 do not provide a full 32k of text RAM to DOS applications running in a window, and this can be disastrous when ANSIPLUS tries to save or view lines for scroll-back. Because of this, the default setting for scroll-back under Windows is to be disabled. If you run all DOS applications full screen, or if Windows and scrolling-back in a window work correctly in an experiment on your system, this feature should be enabled. * If smooth scrolling does not perform well under Windows, or if there are other problems, then smooth scrolling can be disabled in Windows. In general, if scroll-back doesn't work under Windows, then smooth scrolling won't work either. * When Windows is running in 386 Enhanced mode, and a DOS program running in the background outputs a Control-G, the background program's virtual 8086 may not be running fast enough to accurately time the tone. Because of this, the tone can drag out and sound strange. Disabling ANSIPLUS tone generation under Windows restores the original Windows sound driver, but makes the tone frequency and duration non-changeable. 29 ANSIPLUS EXTENSIONS AND THE ANSI STANDARD ANSIPLUS uses a number of added control parameters and includes entire new control functions that are not part of the ANSI X3.64 standard, so do not expect them to be supported by any other drivers or devices. The following added ANSIPLUS functions are not standard ANSI: Esc [!#t Select character set height Esc [!#;...;#e Select graphics mode text treatment options Esc [!#v Select video page Esc [!#;#;#;#;#c Define colors available, select palette, setup blinking Esc [!#;...;#d Enable or disable ANSIPLUS driver features Esc [!#;...;#g Define Control-G beep tone The following ANSIPLUS functions accept standard ANSI parameters, but also accept added non-standard parameters: Esc [#;#h Set video mode Esc [#s Save cursor position, video mode, etc. Esc [#u Restore cursor position, video mode, etc. Esc [#;#J Clear the screen Esc [#;#;#K Clear a line Esc [#;#L Insert lines on the screen Esc [#;#M Delete lines from the screen Esc [#;#@ Insert characters on a line Esc [#;#P Delete characters from a line Esc [#;...;#m Select current color attributes for output characters Esc [#;#n Query ANSIPLUS status: cursor position, colors, etc. Esc [#;...;#p Define key reassignment ESCAPE SEQUENCE RECOGNIZER ENHANCEMENTS To simplify program generation of control sequences, the ANSIPLUS escape sequence recognizer syntax has been relaxed: * Blanks between parameters in escape sequences are ignored; * Commas are allowed as separators in addition to semicolons; * Either single or double quotes may be used around character parameters; * Parameter values over 255 (i.e., up to 32,767) are accepted for certain commands. Plus and minus signs are also accepted. Unrecognized escape sequences are passed through by the driver unaltered. The Esc character is trapped only when followed by a left bracket ("["), so programs that write the escape character (a left arrow) to the screen will continue to do so after the driver is installed. 30 DIRECT ACCESS TO VIDEO RAM VS. BIOS CALLS ANSIPLUS uses direct access to video RAM in all VGA/EGA text and most common graphics modes. However, BIOS calls will be used to output characters for three classes of graphics modes: * Modes with 256 colors; * Modes that require more than 64k bytes of video RAM (i.e., 16 color graphics modes exceeding 800x600 resolution); and * Unrecognized (usually CGA or Hercules) graphics modes. When BIOS calls are used, output is much slower, and "transparent" mode output, graphics mode text treatments, and insert/delete characters are also not supported. Future versions of ANSIPLUS may extend direct video RAM access to some of these modes. INSTALLATION CHECKS ANSIPLUS responds to the Int 2Fh test for ANSI.sys installation. When Int 2Fh is called with AX=1A00h, ANSIPLUS will return AL=0FFh to indicate that ANSI.sys is installed. The Int 2Fh response is expanded if registers BX="AN", CX="SI" and DX="++". Then, in addition to returning AL=0FFh, ANSIPLUS returns a pointer in ES:BX to the ANSIPLUS Int 29h entry point. A further installation confirmation can be made by checking the 8 bytes at ES:[BX-12] for the string "ANSIPLUS". The ANSIPLUS version number will be a 4 character string at ES:[BX-4], containing, for example, "2.04". 31 HOOKED INTERRUPTS To implement all its features, ANSIPLUS attaches itself to nine system interrupts. Two are replaced (1Bh and 29h), and the remaining 7 are supplemented (i.e., ANSIPLUS calls the original interrupt but extends its function). If possible, ANSIPLUS should always be installed after any other drivers that take over any of these interrupts without passing calls through. The following table lists the ANSIPLUS hooked interrupts and reasons for each: +------------------------------------------------------------------------------+ | Table 6-1 | | ANSIPLUS Hooked Interrupts | +----------------------+-------------------------------------------------------+ |Interrupt Description | Reason | +----------------------+-------------------------------------------------------+ |1Bh Keyboard Break | Promote Control-Break to front of key buffer | | | | |29h DOS Write Char | Faster DOS screen output | | | | |09h Keystroke | Screen saver; scroll lock; scroll-back; key buffer | | | extension; smooth scroll toggle; other special key | | | processing | | | | |10h BIOS Video | Palette/DAC control; beep tone generation; screen | | | saver; smooth scroll; scroll lock; scroll-back; BIOS | | | Write TTY ANSI trap | | | | |15h System Services | Key processing | | | | |16h BIOS Get Key | Key buffer management; highlighted key echo; scroll- | | | lock and scroll-back | | | | |1Ch User Timer Tick | Screen saver; smooth scroll; color blinking; beep tone| | | generation | | | | |2Fh Multiplex | Installation checks; special functions; Windows exit | | | processing | | | | |74h PS/2 Mouse Event | Screen saver | +----------------------+-------------------------------------------------------+ 32