ANSIPLUS Enhanced Console Device Driver User's Guide, Release 4.04 Shareware Documentation November 21, 1995 COPYRIGHT (C) 1992-1995 by Kristofer Sweger P.O. Box 378, Larkspur, CA 94977 All Rights Reserved The ANSIPLUS console device driver, supporting utility programs, and this User's Guide are Copyrighted (C) 1992-1995 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, alteration 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 ANSIPLUS is a trademark of Kristofer Sweger. Microsoft, MS-DOS and Windows 95 are registered trademarks and Windows is a trademark of Microsoft Corporation. IBM, OS/2 and PS/2 are registered trademarks of IBM Corporation. NetWare and Novell are registered trademarks of Novell, Inc. 4DOS is a registered trademark of JP Software, Inc. Norton Utilities is a registered trademark of Symantec Corporation. QEMM and DESQview are registered trademarks of Quarterdeck Office Systems, Inc. 386MAX is a trademark of Qualitas, Inc. Other product names are the trademarks of their respective manufacturers. 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 . . . . . . . . . . . . . . . . . . . 8 III. Installing ANSIPLUS Installing the device driver and utility programs . . . . . . 11 Changing the ANSIPLUS startup configuration . . . . . . . . . 15 IV. Using ANSIPLUS Special keyboard and mouse functions . . . . . . . . . . . . 26 Selecting and defining colors . . . . . . . . . . . . . . . . 30 Controlling other ANSIPLUS features . . . . . . . . . . . . . 34 Creating application batch files . . . . . . . . . . . . . . 38 Editing ANSI escape sequence programs . . . . . . . . . . . . 41 V. ANSIPLUS escape sequences Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 42 VI. Technical notes ANSIPLUS and Windows . . . . . . . . . . . . . . . . . . . . 44 ANSIPLUS and the 4DOS or NDOS command shells . . . . . . . . 48 ANSIPLUS and Multitaskers or Task Switchers . . . . . . . . . 49 ANSIPLUS extensions and the ANSI standard . . . . . . . . . . 51 Escape sequence recognizer enhancements . . . . . . . . . . . 52 Direct access to video RAM vs. BIOS calls . . . . . . . . . . 52 Installation check and Interrupt 2Fh API . . . . . . . . . . 53 Hooked interrupts . . . . . . . . . . . . . . . . . . . . . . 54 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 console 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 SuperVGA (SVGA). In addition, the standard personal computer BIOS (the "Basic Input Output System" that is part of the computer's hardware) has limitations that have had to be addressed individually by several TSR (Terminate and Stay Resident) programs or device drivers, by work-arounds and special drivers in major application programs, or by using graphical 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 processor and many applications will be significantly improved. * Screen output should 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 MS-DOS, Windows, OS/2, DESQview or Novell DOS 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 must 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. Registered users also receive: * The TSR-capable registered version of the ANSIPLUS driver, ANSIPLUS.exe. This driver may be loaded into memory from the DOS command line, from a batch file (AUTOEXEC.bat), or from CONFIG.sys with DEVICE=, DEVICEHIGH=, INSTALL= or INSTALLHIGH= commands. The Registered ANSIPLUS driver also doesn't have that pesky time delay in the sign-on message. The registered version is 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 and the ANSIPLUS Int 2Fh API. This information is provided only in the printed manual, and is not included in either the Shareware version or on the Registered diskettes. (Diskette-only registration does not include the printed manual.) * The most recent versions of the ANSIPLUS utility programs and other files in the ANSIPLUS package. * Free BBS updates. Registered ANSIPLUS users can obtain free updates by installing future Shareware versions of ANSIPLUS over their registered copies. The ANSIPLUS installation program will automatically register a Shareware copy when it is installed on a disk that loads a registered copy of ANSIPLUS with its CONFIG.sys. 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 with payment to: Kristofer Sweger P.O. Box 378 Larkspur, CA 94977 Be sure to specify whether you want a 3.5" or 5.25" diskette, and to include the mailing address for your registered ANSIPLUS and manual. Payment may be by check drawn on a United States or Canadian bank, money order, Eurocheque in U.S. dollars, or credit card (Visa or Master Card only). Credit card orders are also accepted by telephone on the ANSIPLUS support line, 415/924-5407, and signed credit card orders may be sent by fax to 415/924-0258. We are pleased to accept purchase orders from established U.S. companies and government agencies. However, orders under $100 must be prepaid. For orders of $100 or more, our terms are net 30 days. Credit references may be required. Pricing is shown in REGISTER.pls. California residents or businesses operating in California must add California sales tax. Other additional charges for shipping to destinations outside the United States and Canada, delivery of a Zip file via CompuServe, or processing a EuroCheque may apply. Multi-computer licenses for use of ANSIPLUS are available upon request at a substantially reduced fee per machine. Call the ANSIPLUS support line for a price quotation. 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, per- mission 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. These files constitute the ANSIPLUS Shareware package: ANSIPLUS.sys ANSIPLUS Shareware console device driver ANSIPLSR.sys ANSIPLUS Shareware reduced size 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 startup 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 the current video mode, video page and colors POPVID.com Restore saved video mode, page and colors PUSHKEYS.com Save the current key reassignments POPKEYS.com Restore saved key reassignments LOCKPAL.com Lock the 16-color palette UNLOKPAL.com Unlock the 16-color palette WINVGA16.com MS Windows 16-color VGA driver palette change VWFD.386 Windowed vs. full screen test Windows VxD APLUS.pif Sample Windows PIF file CPCH.bat Change code page INSTALL.exe Installation program INSTALL.inf Installation control file INSTALL.cve Installation data 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 or CD-ROM, shipping and handling, as long as the total per diskette does not exceed US $6.00 in the United States and Canada or US $10.00 internationally, and the total per CD-ROM disk does not exceed US $50.00. * 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. 3 Because ANSIPLUS is distributed as Shareware, the driver contains internal checks to increase its resistance to tampering. Users are therefore NOT licensed to alter or "patch" the driver, and the driver will terminate installation or will not work properly if it detects attempts to change it. All rights not expressly granted here are reserved to Kristofer Sweger. 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, whether you have registered or not. There are several ways you can reach ANSIPLUS support: * Electronic mail via CompuServe at 72713,1241 * Electronic mail via Internet at 72713.1241@compuserve.com * Voice telephone at 415/924-5407 * Fax at 415/924-0258 * U.S. mail at P.O. Box 378, Larkspur, CA 94977 USA 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: * What is the problem, or what is not behaving as expected? * What exactly must be done to cause the problem to appear? * What did you do to try to fix or work around the problem? * What is your software and hardware environment? This includes the version of ANSIPLUS you are using, your computer type, DOS version, video controller, any memory managers, other device drivers or TSRs loaded, and any other software or hardware in use at the time. 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 SVGA, VGA and EGA display capabilities: Mode recognition For any SVGA/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. On a standard VGA, for example, ANSIPLUS supports 80 column text with 25, 26, 28, 30, 33, 36, 40, 44 and 50 lines. Smooth scrolling ANSIPLUS supports smooth scrolling of the screen, 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 SVGA/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. The screen saver can also reduce monitor power consumption if the video BIOS and monitor support VESA power management. 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. Copy and paste It is often desirable to bring back data or commands that have scrolled off the screen or to transfer information between programs, but without having to retype the data. And under Windows, it is often desirable to copy text between a full screen application and the Windows clipboard without having to switch into a window. ANSIPLUS addresses both these needs by letting you use the mouse or keyboard to select text, copy it to the clipboard, and paste it to the keyboard. See "Special Keyboard and Mouse Functions" in Chapter 4 for more information about this feature. 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. 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). 6 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 "typematic") 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. The rate at which repeated keys are generated is also configurable. Key stacking ANSIPLUS supports key stacking, which can load the keyboard buffer with a series of keystrokes and feed them into programs or commands as if they had been typed at the keyboard. This feature can be useful for automating startup of programs, software testing, and demonstrations. Keys can be added to the buffer by ANSI escape sequence, by ANSIPLUS utility program command, or, for users of the 4DOS 4.0+ or NDOS Version 7.0+ command shells, by KEYSTACK command. Beep tone The standard personal computer BIOS Ctrl+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 a timer 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. 7 OTHER ANSIPLUS FEATURES Other ANSIPLUS features include: User control Menu driven, mouse controllable 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 pure code (18K to 29K) and other code/data (about 6K) sections, placing the code in XMS upper memory blocks (from 640K to 1M), in high memory (1M to 1M+64K), or in expanded memory (EMS), and leaving only the other code/data part in either low or upper memory. The registered driver can be loaded as either a TSR program or a device driver. Reduced driver For systems with very limited available memory, a reduced capability driver that is 35 percent smaller may be used instead of the full capability ANSIPLUS driver. Windows aware ANSIPLUS features have been tested and adjusted for maximum compatibility in Windows 95, Windows 3.x and Windows NT DOS sessions, both full screen and within a window. The ANSIPLUS driver detects when Windows is running, and automatically disables or alters certain features, such as the screen blanker, that may interfere. OS/2 compatible ANSIPLUS can be used in OS/2 2.x and OS/2 Warp DOS sessions, loaded either as a standard DOS device driver by CONFIG.sys or as a DOS TSR. The driver automatically makes minor adjustments under OS/2, such as suppressing the ANSIPLUS signon message because virtual DOS machines are created and initialized so often by OS/2. Multitaskers and ANSIPLUS detects and adjusts for DESQview. Under DESQview, task switchers the driver is loaded separately for each window that needs it. Under task switchers like MS-DOS DOSSHELL, each task automatically has an independent ANSIPLUS as its console. ANSI support All MS-DOS ANSI.sys escape sequences are supported, plus about two dozen other ANSI and VT-100 escape sequences for clearing the screen, erasing, inserting and deleting lines and characters, scrolling, page selection, tab control, and cursor positioning. ANSIPLUS also enhances many escape sequences by accepting extra parameters that increase their power. 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. 8 Key processing ANSIPLUS includes several special key processing options: (1) sticky shift keys for one handed or mouth stick typists; (2) the Shift+alphabetic keys can cause Caps-Lock to unlock, much like a typewriter releases its shift lock whenever a shift key is pressed; (3) the Enter key can restore Caps-Lock after it was unlocked by a Shift+alphabetic key, thus restoring Caps on completion of an "entry"; (4) Ctrl+C can cause a Ctrl+Break, for those users who prefer the Ctrl+C key; and (5) the DOS "Non-Destructive" read function can return the last key in the keyboard buffer instead of the first, so that it always reflects what has last been typed. Key reassignment ANSIPLUS has the ability to translate single keystrokes to full commands or other pre-determined key sequences. These key reassignments can be applied either to keys entered through DOS or to all keys entered via BIOS Interrupt 16h. Both expansion of keys and changes to key reassignments can also be enabled or disabled independently. When key reassignment changes are disabled, a distinctive tone sounds on any attempt to redefine a key, making it easy to detect ANSI-type files that contain key redefinitions. Key reassignments can also be saved and restored, allowing simple restoration of a standard key set after using special reassignments in an application. Scrolling regions The driver has the ability to restrict DOS, ANSI and video BIOS output to any user-defined sub-screen region or "window." This can simplify writing or adapting certain applications, because screen output can be directed to any desired area of the screen while a subroutine or program "thinks" it is using a normal screen. 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. 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. 9 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. 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 check To facilitate developing applications that can use ANSIPLUS and Int 2Fh API features, ANSIPLUS responds to standard Int 2Fh ANSI.sys installation checks, and includes extensions that can distinguish ANSIPLUS from ANSI.sys. The ANSIPLUS Int 2Fh API provides special functions for programmers. Free BBS Updates When a Shareware copy of ANSIPLUS is installed on a disk that loads a Registered copy of ANSIPLUS from CONFIG.sys or AUTOEXEC.bat, the INSTALL program will convert the new Shareware ANSIPLUS.sys driver into a Registered ANSIPLUS.exe driver with the same serial number and signon message as the Registered ANSIPLUS.exe already on the disk. Registered users can thus benefit from future improvements to ANSIPLUS at no cost, if they have access to CompuServe, the Internet or a bulletin board system (BBS) that maintains recent Shareware versions of ANSIPLUS. 10 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, CONFIG.sys and AUTOEXEC.bat 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 and AUTOEXEC.bat. Starting with MS-DOS 6.0, the CONFIG.sys file can contain menus and multiple configuration blocks. When a CONFIG.sys menu is being used, a new ANSIPLUS installation will require selecting a configuration block to receive the ANSIPLUS DEVICE= command, and an update will require selecting a block that either already refers to ANSIPLUS, or to which it will be added. INSTALL makes an initial choice of configuration block, and the user can correct this before copying the ANSIPLUS release files by using the "Revise Parameters" option on the Installation menu. The INSTALL program also 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. For those who are not content to use default driver feature and other settings, after the release files have been copied to the target drive, the configuration section of the INSTALL program 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 15. 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. 11 International Usage If you are using the MS-DOS KEYB program to set up your keyboard, the following command MUST be executed after you load KEYB, otherwise most ANSIPLUS keyboard related features will not work: SETAPLUS LINK KEYEVENT The INSTALL program will automatically add this command to your MS-DOS AUTOEXEC.bat file if it finds a reference in it to KEYB. Relinking the key event interrupt is not necessary under Novell DOS with Novell's KEYB, because it is directly compatible with ANSIPLUS. If you are using the DISPLAY.sys device driver for code page switching, the ANSIPLUS.sys device driver must be installed before DISPLAY.sys in your CONFIG.sys file. The INSTALL program will automatically handle this in most cases. However, under DOS 6.0+, if ANSIPLUS is installed in a configuration block that will be processed by MS-DOS after the configuration block that contains DISPLAY.sys, this situation will not be detected by INSTALL. This must be corrected by directly editing CONFIG.sys. Because of a bug in Microsoft Windows 3.1 that prevents ANSIPLUS (or any other ANSI driver) from being localized when the DISPLAY.sys driver is also used, INSTALL will automatically add the following command to AUTOEXEC.bat: SETAPLUS LOCALCON Or, if both KEYB.com and DISPLAY.sys are used, the command will be: SETAPLUS LINK KEYEVENT LOCALCON See "ANSIPLUS and Windows" starting on page 44 for Windows configuration changes that you must make if you will be running Windows and DISPLAY.sys. The "LOCALCON" keyword in the above commands causes the ANSIPLUS "CON" driver in memory to be renamed as "CONAPLUS". Unfortunately, the MS-DOS CHCP command calls DOS Int 21h function 6602h, which searches the DOS device chain for the "CON" driver installed before DISPLAY.sys, and because it was renamed, reports an "Access Denied" error. The best work-around depends on whether you will be using Windows: * If Windows will NOT be used, remove the word "LOCALCON" from the SETAPLUS command in AUTOEXEC.bat; or * If Windows WILL be used, the CPCH.bat file supplied with ANSIPLUS should be used as a replacement for the DOS CHCP command. Thus, for example: CPCH 850 will temporarily rename the ANSIPLUS driver as "CON", change the code page to 850, and then rename the driver back to "CONAPLUS". 12 Disk Compression Utilities On systems using Stacker or similar disk compression utilities that can change the hard disk drive letters around, INSTALL should still be able to locate CONFIG.sys, AUTOEXEC.bat or the ANSIPLUS driver file if it was previously installed. When CONFIG.sys is not found on the (hard disk) target drive, other drives will be searched for it, starting with drive C:. AUTOEXEC.bat is then assumed to reside on either the target drive or the same drive as CONFIG.sys. And if the ANSIPLUS driver is not found where CONFIG.sys says it will be, the same path on other drives will be searched for it as well. In the event that these search rules still cannot locate the correct files, a system environment variable (SET ANSIPLUS=d:) may be used to identify the drive with CONFIG.sys and the ANSIPLUS driver, and this will override the search. Memory Loading Optimizers It is strongly recommended that ANSIPLUS be permanently excluded from automated memory loading optimizations, such as DOS 6+ MEMMAKER, QEMM OPTIMIZE, or 386MAX MAXIMIZE. There are three reasons for this: * The ANSIPLUS "/U" memory loading option, which loads ANSIPLUS code to upper memory blocks, is likely to confuse the optimizers because the driver memory requirements change depending on whether ANSIPLUS is loaded low or high, and when the driver is loaded low, ANSIPLUS allocates some upper memory blocks itself. * Changes you make at a later date with the NEWAPLUS program to driver table sizes can result in a larger load size for the ANSIPLUS driver. This could cause the driver or something loaded after it to be loaded low instead of high, either because the driver is larger than the (QEMM) response file expects, or it has become too large for everything to fit in the space available. * ANSIPLUS has seven memory loading options that may be easily selected using NEWAPLUS.exe. Some of these options let you place part of the driver in EMS memory or HMA, which the memory managers cannot do. The memory managers give only two choices: low or high. You therefore have more control using NEWAPLUS. ANSIPLUS can be permanently excluded from MEMMAKER by adding a line containing "*ANSIPLUS" to the file MEMMAKER.inf. Exclusion from QEMM's OPTIMIZE is accomplished by adding a line containing "ANSIPLUS" to the file OPTIMIZE.exc in the QEMM directory (create this file if it doesn't exist). Loading ANSIPLUS as a TSR The registered ANSIPLUS driver, ANSIPLUS.exe, can be loaded as a TSR, and this is the only recommended Terminate-and-Stay-Resident method for loading ANSIPLUS. The ANSIPLUS INSTALL program will not automatically configure ANSIPLUS to be loaded in this manner, so the user must either modify CONFIG.sys to use an INSTALL= or INSTALLHIGH= command, or must change AUTOEXEC.bat to execute ANSIPLUS.exe as a program. Once this has been done, however, NEWAPLUS will be able to find and reconfigure the ANSIPLUS.exe driver referred to by CONFIG.sys or AUTOEXEC.bat. The Shareware ANSIPLUS.sys driver cannot be loaded directly as a TSR. However, the Quarterdeck device driver loader DEVICE.com can be used to load the 13 Shareware driver as a TSR. But because loading ANSIPLUS changes the system console, DEVICE does not completely install the driver, at least as far as the MS-DOS command shell, COMMAND.com, is concerned. This can be corrected by entering a CTTY CON command after ANSIPLUS has been loaded. The DEVLOD.com device driver loader, supplied with the book Undocumented DOS, is also able to load ANSIPLUS.sys, but it can also cause problems loading a new console device driver. It changes all references to the old CON device in the DOS System File Table to point to the new console, which is correct under standard MS-DOS. However, if DEVLOD is used to load ANSIPLUS.sys under Windows 3.1, the System File Table changes can cause a Windows crash when a second DOS session is started. OS/2, DESQview and Task Switchers Using ANSIPLUS with multitasking operating systems and task switchers is discussed in "ANSIPLUS and Multitaskers or Task Switchers", starting on page 49. This section includes special information about OS/2, DESQview and other task switchers such as DOSSHELL. Reading this section is especially important if you intend to use ANSIPLUS with DESQview. Replacement CON drivers generally will not work correctly in a DESQview window, but if the right procedures are followed, ANSIPLUS Release 4.00 or later should be compatible. Examples The following 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 (named ANSIPLUS.zip in this example), use the following procedure: (1) Create a temporary 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. This directory must be different from the directory that will receive the installed ANSIPLUS files. (2) Unzip the files into the directory with the command: PKUNZIP ANSIPLUS (3) Then enter the command: INSTALL After installation is complete, you may delete the files in the temporary sub-directory (but keep the ZIP file as a backup). * To install ANSIPLUS on bootable disk B:, from hard disk directory C:\APLUS, enter the command: C:\APLUS\INSTALL B: 14 CHANGING THE ANSIPLUS STARTUP CONFIGURATION Changes to the startup configuration for ANSIPLUS are made with the NEWAPLUS program. (INSTALL also lets you make these changes, but INSTALL.exe is actually a tiny program that calls NEWAPLUS.exe to perform the installation.) All changes that you make with the NEWAPLUS.exe program will take effect only after you restart your computer. All startup configuration changes made by NEWAPLUS (except for the ANSIPLUS loading option) are installed by changing tables in the ANSIPLUS driver file. Because of this, some anti-virus and disk compression software may complain after you have used NEWAPLUS that the driver file or the system configuration has been altered. Just ignore this complaint. You run NEWAPLUS with a command of the form: NEWAPLUS where is usually the drive letter for a bootable diskette or hard disk partition with ANSIPLUS installed. If is omitted, the drive that was originally used to load MS-DOS will be selected. The may also specify the full file path name of the ANSIPLUS driver file you want to reconfigure, in which case those few revision options that affect CONFIG.sys or AUTOEXEC.bat will be unavailable. After NEWAPLUS confirms that the target disk or file contains a valid ANSIPLUS driver, you are presented with a startup configuration menu that has twelve 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. 15 Version * ANSIPLUS 4.00 or later lets you select between two device drivers: the full driver ("ANSIPLUS"), and a reduced capability driver ("ANSIPLSR"). The only advantage of the reduced capability driver is that it requires about 35 percent less memory after it is loaded. To save this memory, five ANSIPLUS features are removed: Scroll-back, copy/paste, direct output to video RAM in graphics mode, graphics mode text treatments, and monochrome VGA emulation on a color VGA. Loading Option ANSIPLUS can be loaded into memory up to seven different ways, depending on your computer's capabilities and what is contained in CONFIG.sys. These loading options allow you to control ANSIPLUS's requirements for each type of system memory: low memory below 640K, XMS upper memory blocks from 640K to 1M (UMB memory), high memory from 1M to 1M+64K (HMA), or EMS expanded memory. The following table shows the differences in memory breakdown (in K-bytes) for the full capability ANSIPLUS driver. Notice that each option in the table uses 64K of EMS memory. EMS memory is the recommended location for holding scroll-back data for the ANSIPLUS driver. In order to have access to EMS memory, an EMS memory manager such as EMM386 or QEMM386 must be loaded by CONFIG.sys before the ANSIPLUS driver is loaded, and it must have its EMS RAM and page frame enabled. +----------------------------------+------+------+------+-----+ | Loading Method | Low | UMB | HMA | EMS | +----------------------------------+------+------+------+-----+ | Load to low memory | 35 | 0 | 0 | 64 | | Load code to upper memory blocks | 6 | 29 | 0 | 64 | | Load code to HMA high memory | 12 | 0 | 23 | 64 | | Load code to EMS expanded memory | 7 | 0 | 0 | 64 | | Load driver high to UMB memory | 0 | 35 | 0 | 64 | | Load driver high, code to HMA | 0 | 12 | 23 | 64 | | Load driver high, code to EMS | 0 | 7 | 0 | 64 | +----------------------------------+------+------+------+-----+ Usage of low memory may not be the only consideration when deciding how to load ANSIPLUS. The following gives further information about each loading option: * ANSIPLUS can be loaded into low memory below 640K. This is the default. The following CONFIG.sys command loads ANSIPLUS to low memory: DEVICE=ANSIPLUS.sys * ANSIPLUS can load its code into upper memory blocks. At load time, the driver can divide itself into two sections: pure code totaling 13K to 29K depending on driver version and available upper memory, and other code/data totaling 5K to 11K. The code can be placed in XMS upper memory blocks (from 640K to 1M), in high memory (1M to 1M+64K), or in expanded memory (EMS), leaving only the other code/data 5K to 11K in low memory. Under DOS 5.0 or later, 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 16 * ANSIPLUS can load its code into the high memory addressed just above 1 megabyte (the "HMA"). Under DOS 5.0 to 6.22, with the DOS=HIGH line in CONFIG.sys, ANSIPLUS shares this memory with DOS; if DOS=HIGH is not used, but an XMS driver is installed, the HMA is obtained from the XMS driver; or, for earlier DOS versions or systems not using an XMS driver, the HMA is taken in the same manner as the VDISK.sys driver allocates extended memory. When ANSIPLUS is loaded into the HMA, 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, expanded memory or low memory instead. The following CONFIG.sys command will load ANSIPLUS into the high memory area: DEVICE=ANSIPLUS.sys /H * ANSIPLUS can load its code into expanded memory (EMS) which conforms to LIM (Lotus-Intel-Microsoft) Specification 4.0, eliminating the need for up to 29K of scarce UMB, HMA or low memory resources. However, this loading method is not recommended unless you really need to free up the extra memory. Executing in EMS carries a performance penalty because the EMS pages must be mapped and restored each time ANSIPLUS needs to execute in EMS, and this can be especially noticeable under Windows with a slower microprocessor. And because expanded memory may be shared with other programs, drivers or TSRs, there is a small chance of a software interaction that may prevent an application from running, keep Windows from loading, or cause the system to fail. (For example, Version 6 of 386MAX will refuse to let Windows start in 386 Enhanced mode when ANSIPLUS is running in EMS. This limitation does not exist for the EMM386 or QEMM386 memory managers.) If you experience any problems using ANSIPLUS in EMS, do not use the feature. Load ANSIPLUS into XMS upper memory, the HMA, or low memory instead. The following CONFIG.sys command will load ANSIPLUS into expanded memory: DEVICE=ANSIPLUS.sys /E * ANSIPLUS can be loaded high by DEVICEHIGH or equivalent. The following CONFIG.sys command will load ANSIPLUS high using EMM386: DEVICEHIGH=ANSIPLUS.sys * ANSIPLUS can be loaded high, and then its code can be placed in HMA. This requires only 11K of XMS upper memory after ANSIPLUS has completed its initialization (5K for the reduced driver). However, upper memory space for the entire driver must be available when it is first loaded: DEVICEHIGH=ANSIPLUS.sys /H * ANSIPLUS can be loaded high, and then its code can be placed in EMS: DEVICEHIGH=ANSIPLUS.sys /E 17 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. * The keyboard repeat rate determines how fast keys will be generated when a key is held down and not lifted. For systems with enhanced keyboards, ANSIPLUS lets this rate be configured anywhere from 2 to 300 characters per second. For most applications, an ANSIPLUS repeat rate setting greater than 30 characters per second will take precedence over the keyboard repeat rate set by other programs, such as the DOS MODE program. If desired, the ANSIPLUS repeat rate can be disabled and the DOS rate used instead. * The keyboard typematic delay, which determines how long a key must be held down before repeated keys will start to be generated, is also configurable. ANSIPLUS accepts four settings from 250 ms to 1000 ms. * ANSIPLUS supports sticky shift keys for one handed or mouth stick typists. When this feature is enabled, if the user strikes a Shift, Ctrl or Alt key once, it will remain "on" until the next normal key is struck, and then will be reset. If one of these shift keys is pressed twice, it will be locked on for all subsequent keystrokes until hit a third time to turn it off. * Some "point-of-sale" keyboards include special "00" or "000" keys for entry of multiple zeros, but generate the zeros without simulating the lifting of the key between the characters. Because ANSIPLUS will normally suppress repeated digits, the multiple-zero keys on these keyboards will enter only a single zero. A configurable feature is provided to allow repeated zeros when using such keyboards. * 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. * 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. ANSIPLUS 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 Ctrl+C key combination than with Ctrl+Break, ANSIPLUS has an option to generate a keyboard break whenever Ctrl+C is entered. 18 * The "Non-Destructive" read function of the DOS driver 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 Ctrl+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. * Key stacking can be disabled to use another key stacking driver (for example, NDOS KEYSTACK.sys), or when typing files that contain unknown ANSI escape sequences that might execute undesired commands. When disabled, a warning tone will sound on any attempt to stack keys by ANSI escape sequence. * Like the MS-DOS ANSI.sys driver, ANSIPLUS supports the "/K" command tail switch when the driver is installed. This option disables the driver's recognition of enhanced (101-key) keyboards, and forces it to assume that an 84-key keyboard is in use. Assigning Keys * 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. * Ordinarily, key reassignment applies only to input keys requested from DOS, so programs that bypass DOS and use BIOS Interrupt 16h for keyboard input will not have any keys reassigned. This is usually desirable, since major applications generally have built-in assumptions about the meaning of function and Alt keys, and these should be operative. An ANSIPLUS feature is provided for those cases when you want to reassign keys for applications that bypass DOS and use Int 16h for keyboard input. If you enable this feature, key reassignment will apply to all keystrokes entered through both Int 16h and DOS. If it is disabled, key reassignment will only apply for keys requested from DOS. * ANSIPLUS can also prevent ANSI key reassignment redefinition. This can be useful before trying ANSI files that contain unknown ANSI sequences that might redefine keys to execute undesired commands. A warning tone (like the theme from "Dragnet") will sound whenever an attempt to redefine a key reassignment is detected. If this feature is enabled by either NEWAPLUS or SETAPLUS, SETAPLUS must be used to disable it -- it cannot be disabled by an escape sequence alone. * 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. If you save and restore key reassignments with the PUSHKEYS.com and POPKEYS.com programs, the storage space must be large enough for all saved key reassignments plus the current reassignments. 19 Tone Definition * The ANSIPLUS driver includes a timer-interrupt controlled Ctrl+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 is running in 386 Enhanced mode, and a DOS program running in the background outputs a Ctrl+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. 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 (the "OEM" colors) will be loaded when the video mode changes. * Some 256-color DOS applications assume that the OEM 256-color palette has been loaded when the 256-color mode was selected, and never define the colors that they will use. A feature is provided to disable ANSIPLUS color loading for DOS 256-color modes if you are running such an application. * Some 256-color drivers for Windows apparently assume that the OEM 256-color palette has been loaded when the 256-color mode was selected, and never define the colors that Windows will use. Because of this, ANSIPLUS normally does not load its colors when a 256-color mode is selected under Windows. However, a separate feature is provided to allow this if desired. * 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. 20 * 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. * 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. 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 when not in full screen DOS sessions under OS/2 or Windows, in DESQview, and when games or other programs that change 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 thirty minutes. * The ANSIPLUS screen blanking technique, which sets the VGA sequencer clock mode register, apparently is incompatible with a few VGA controllers (eg., Cirrus Logic GD610/20). For such controllers, a special feature is provided to select an alternative (EGA compatible) method which blanks the screen using the attribute controller instead. * The ANSIPLUS screen saver can reduce the power consumed by your monitor if both your video controller BIOS and monitor support VESA power management. When VESA power management is enabled, after the screen has been blank for 5 minutes the monitor will be placed in standby mode. After 10 minutes, it will change to "suspend" mode, and after 15 minutes the monitor will be turned off. * As a "last resort" test for system activity, the screen saver can read scan codes from the keyboard controller at port 60h. This test should only be needed when you are running an application that completely takes over all keyboard interrupts and directly controls the screen display as well. On some computers, enabling this feature can interfere with processing of the arrow and page up/down keys on enhanced keyboards, or with a PS/2 type mouse, so the feature should be disabled unless it is really needed to keep the screen saver from blanking the screen during a specific application. * 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 this interrupt is used for another purpose on your computer, this feature should be disabled. 21 * The DOS console drivers do not show a cursor on the screen when using a graphics mode. ANSIPLUS can display a pseudo-cursor when keyed entries are requested by DOS in a graphics mode. If this feature is desired, it can be enabled. If it interferes with the appearance of a graphics mode program, it should be left disabled. * Because almost all applications that use 256-color graphics modes assume that DOS does not place a cursor on the screen, the ANSIPLUS pseudo-cursor is normally disabled when in a 256-color mode. If desired, you can enable the cursor. * 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. * ANSIPLUS contains an internal storage area for saving and restoring driver context information (rows and columns, colors, display modes, etc.). The default size allows 25 items to be saved, but this can be configured to a larger value if needed. Screen Scroll-Back * 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 not desired, or if storage of the saved lines in either expanded memory (EMS) or unused portions of the video RAM is found to interfere with something, it can be disabled. * Ordinarily, when ANSIPLUS is initialized by DOS, it will try to allocate 64K of expanded memory (LIM EMS 4.0) for scroll-back. When EMS is used for scroll-back, storage capacity will be about 1,000 lines, and the scroll-back data will be preserved as long as the computer is on. (If the ANSIPLUS code was loaded into EMS, it will share the same 64K area as scroll-back, reducing capacity by 40 percent.) If EMS memory is unavailable, then scroll-back will be stored in unused portions of the video RAM instead, cutting capacity to about 500 lines, which will be lost every time the display mode changes. A configurable feature is provided that can prevent DOS EMS memory from being allocated for scroll-back and force any scroll-back data to reside in video RAM. * Under Windows, when a 386 Enhanced Mode DOS session starts, ANSIPLUS will try to allocate 64K of private expanded memory (EMS) for scroll-back (48K if ANSIPLUS code was loaded into EMS). If the EMS is not available (for example, if the Windows PIF file for the application does not provide expanded memory), then video RAM will be used for scroll-back instead. ANSIPLUS provides a configurable feature that can prevent Windows EMS from being allocated for scroll-back and force any Windows DOS session scroll-back to reside in video RAM. This is not recommended, however, because scroll-back in video RAM under Windows is not reliable when used with many Windows video drivers. 22 * The recommended location for scroll-back data under Windows is expanded memory (EMS). When EMS memory cannot be used, if you want to use scroll-back under Windows, you must enable a feature that allows using video RAM for scroll-back instead. When running DOS applications in 386 Enhanced Mode, Windows will not maintain a full 32K of text mode RAM unless the Windows PIF file specifies "High Graphics" and "Retain Video Memory", and even then some Windows 3.1 video drivers (eg., 256-color ET-4000) will not work correctly when video RAM outside the visible screen is accessed, resulting in loss of scroll-back text or incomplete updating of the screen. You therefore should exercise caution before relying on this feature. For further information, see "ANSIPLUS and Windows" starting on page 44. * Another feature only applies when video RAM is used instead of EMS to hold scroll-back data. On systems running a suitable XMS driver such as QEMM or HIMEM, ANSIPLUS can allocate XMS memory to hold scroll-back data when changing video modes or running graphics applications (including Windows). DOS sessions under Windows 3.1 can also use XMS memory for this purpose if they are run from a PIF file that provides at least 32K of XMS memory. If ANSIPLUS is loaded into the High Memory Area (HMA) and is not sharing this area with DOS, then scroll-back will be preserved in HMA instead of XMS memory. Because calls to some XMS drivers may require a lot of stack space, this feature should be disabled if you have reliability problems during display mode changes. And because the feature is now rarely needed, if it is disabled at system startup, the code to perform its function will be deleted from the driver (saving 650 bytes), and the feature will not operate. * 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. Under Windows 3.1, when a DOS session is running in a window, some Windows video drivers (for example, the Microsoft Windows 3.1 VGA driver) trap BIOS scrolling calls completely and do not pass them through to the DOS virtual 8086, making it impossible for ANSIPLUS to reliably capture lines scrolled by BIOS call when Windows is running. * 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. * To simplify writing or adapting applications, ANSIPLUS has the ability to restrict DOS, ANSI and BIOS screen output to user-defined scrolling regions or "windows." Because scrolling regions are generally used only within applications, when a subscreen scrolling region is in effect, lines scrolled off the top of the region are not usually captured for scroll-back. An option is provided to capture such lines. 23 * When EMS memory is not used for scroll-back, 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. Almost 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, a few applications, such as the Norton Utilities Version 7, appear to use the second video page without ever selecting it to save the original contents of the screen as the program starts up. This action will wipe out any scroll-back data in the second page, and when the original screen is cleared by the program, scroll-back lines may be stored into the saved screen, causing gibberish to be restored to the screen when the program terminates. To address this problem, a configurable feature is provided to protect the second video page from scroll-back storage. However, when this feature is enabled, storage capacity for scroll-back in the video RAM will be reduced by one page. Other * 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. * 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. * Because scrolling performance is reduced when Windows is running, smooth scrolling under Windows may appear jerky even though it works correctly under DOS. Smooth scrolling also may interfere with many Windows video display drivers when the DOS session is run in a window, not full screen. For example, the 256-color drivers for the Tseng ET4000 may leave undrawn black areas on the screen when scrolling occurs in a window while smooth scrolling is active. Because of these problems, smooth scrolling is disabled by default under Windows, and is kept disabled unless the VWFD.386 Windows virtual device driver (VxD) is installed. See "ANSIPLUS and Windows 3" starting on page 44 for further information. * The smooth scrolling rate is configurable. The rate is expressed in scan lines per vertical retrace, and may range from 1 to 8. The rate should be selected carefully, because scrolling will not be completely smooth if the rate does not divide evenly into the number of scan lines per character. 24 * 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. * ANSIPLUS normally handles all text mode scrolling itself directly in the video display RAM. This may confuse some other device drivers or TSRs that are installed and need to know when the screen is being scrolled. In such cases, a feature can be enabled to cause BIOS calls for screen scrolling. * On 80386 or later systems, 32-bit block moves can be used for faster text mode scrolling. Unfortunately, a few video controllers cannot handle this properly, so this feature must disabled by default. If scrolling and scroll-back work reliably with 32-bit scrolling enabled in an experiment on your system, this feature should be permanently enabled by NEWAPLUS. * In full screen operation, ANSIPLUS should automatically detect whether the current running program is using the mouse, and not try to take over the mouse for copy and paste. In case this mouse activity detection logic fails, and ANSIPLUS interferes with a program's mouse usage, a configurable feature is provided to correct the problem by keeping ANSIPLUS from taking over the mouse unless the screen has been frozen by the Scroll Lock key. This feature affects only standard DOS and full screen Windows or OS/2 sessions, because ANSIPLUS always requires that Scroll Lock be on before it takes over the mouse in windowed OS/2 or Windows sessions or in DESQview windows. This keeps the mouse from being activated as you move it from window to window or when you leave the mouse cursor sitting over an ANSIPLUS DOS window. 25 IV. USING ANSIPLUS This chapter describes your controls over ANSIPLUS when it is running. Five subjects are covered: special keyboard and mouse functions; selecting and defining colors with the SETCOLOR.exe utility program; controlling other ANSIPLUS features with the SETAPLUS.exe utility program; creating batch files for configuring applications; and editing ANSI-type escape sequence programs and files with the ANSICOM.exe program. SPECIAL KEYBOARD AND MOUSE FUNCTIONS Hot Keys To access its special keyboard control functions, ANSIPLUS uses three hot key combinations, all involving the Scroll-Lock key: * To activate scroll freeze, scroll-back, and copy/paste, use the Scroll-Lock key alone, or combine it with the Alt key: Scroll-Lock Enable or disable Scroll Lock: scroll freezing, scroll-back and copy/paste Alt+Scroll-Lock Enable or disable Scroll Lock (alternative keys) * To turn smooth scrolling on and off, add a Shift key: Shift+Scroll-Lock Enable or disable smooth scrolling * To blank the screen immediately (if the ANSIPLUS screen saver is enabled), add Alt and Ctrl keys to Scroll-Lock, or use the alternative Alt+Shift+Num Lock key combination: Alt+Ctrl+Scroll-Lock Blank the screen immediately Alt+Shift+Num Lock Blank the screen immediately (alternative keys) Scroll Lock 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 Scroll Lock 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+Tab Scroll up one-half page 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 Ctrl+Home Delete all scroll-back older than that visible on the screen Ctrl+End Delete all scroll-back visible on the screen or newer Left arrow View a lower numbered display page Right arrow View a higher numbered display page 26 Gray Plus Set a bookmark at the current scroll-back location Gray Minus Remove the bookmark at the current scroll-back location Gray Enter Display the next bookmark location Escape Cancel Scroll Lock, return to normal key processing Scroll lock Cancel Scroll Lock, return to normal key processing Insert Paste the current text selection to the keyboard from the screen, the local clipboard or the Windows clipboard. Then cancel Scroll Lock (see "Copy and Paste" below) Ctrl+Insert Signal that the arrow keys will be used to start a text selection for copy and paste (see "Copy and Paste" below) Delete Clear the clipboard 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 shift key is held down. Copy and Paste ANSIPLUS supports copy and paste so that you can recover data or commands that have scrolled off the screen without having to retype the data. Under Windows, this feature lets you copy text easily between a full screen text mode DOS application and the Windows clipboard without having to switch to a window. To hold text for later pasting to the keyboard, the ANSIPLUS driver contains a local clipboard. The default size of this clipboard is limited: 384 bytes plus the amount of free space in the storage area for key reassignments, and the driver will issue a buffer full tone if it ever overflows. If this happens, the local clipboard capacity can easily be increased by raising the size of the ANSIPLUS key reassignment tables with the NEWAPLUS.exe configuration utility. Whenever Scroll Lock is on, ANSIPLUS lets you use the mouse and/or keyboard to select text, to copy it to the clipboard, or to paste it to the keyboard. When Scroll Lock is off, if the currently running program or command shell does not use the mouse, the mouse may be used for copy and paste without requiring entry of the Scroll-Lock key. The local clipboard is cleared only when the first text selection is added to it after Scroll Lock has been turned on, or when key input pasted from the Windows clipboard is completed. Thus, a series of text selections can be added to the clipboard from various places on the screen or scroll-back, and then left in the clipboard until you need to paste them. Because the clipboard can retain data for a long time, you should be sure of what is in your clipboard before you paste to the keyboard. In Windows, whenever selected text is saved to the clipboard (by the Enter key or right mouse button click), the local clipboard is automatically copied to the Windows clipboard so that other programs may have access to the data. 27 Pasting text to the keyboard is simple, once it has been selected or if it is already present in the Windows clipboard: just hit the Insert key or click once on the left mouse button after Scroll Lock is on. Selecting text with the keyboard is a little more complicated because it requires two steps: starting the selection by positioning the cursor to the beginning of the text, and then extending the size of the selection. Selecting text with the mouse is covered below in "Using the Mouse". The following keys are used when starting a text selection: Insert Paste the local or Windows clipboard to the keyboard Escape Cancel the text selection Delete Clear the clipboard Space Select the word at the cursor position Home Move the cursor to the start of the current line End Move the cursor to the end of line Up arrow Move the cursor up one line Down arrow Move the cursor down one line Left arrow Move the cursor left one character Right arrow Move the cursor right one character Once a text selection appears on the screen (i.e., after hitting the Space bar to select a word or after selecting something with the mouse), the following keys can be used to extend and complete it: Insert Paste the selection to the keyboard Alt+Insert Paste selection, suppressing leading spaces on each line Enter Complete the selection and add it to the clipboard Alt+Enter Add selection to clipboard, suppressing leading spaces Escape Cancel the text selection Delete Clear the clipboard Tab Toggle between lines and rectangular area selection Space Add a word to the selection Home Extend the selection to the start of the current line End Extend the selection to the end of line Up arrow Extend the selection to the line above Down arrow Extend the selection to the line below Left arrow Delete the last character from the selection Right arrow Add one character to the end of the selection Using the Mouse In order to use the mouse for copy and paste or for scrolling back, you must first "wake it up" by moving it or pressing one of the buttons. This tells ANSIPLUS that the mouse will be used, and the mouse cursor will appear on the screen. If the program that is running already was using the mouse, then Scroll Lock must be on or ANSIPLUS will NOT take control of the mouse. 28 In full screen operation, ANSIPLUS should automatically detect whether the current running program is using the mouse, and not try to take over the mouse for copy and paste. In windowed OS/2 or Windows sessions or in DESQview windows, ANSIPLUS requires that Scroll Lock be on before it takes over the mouse. This keeps the mouse from being activated as you move it from window to window or when you leave the mouse cursor sitting over an ANSIPLUS DOS window. Once ANSIPLUS recognizes the mouse, if you move the mouse cursor to the top line on the screen, the screen will scroll backward (turning on Scroll Lock if necessary). If the screen is scrolled back, moving the cursor to the bottom line will cause the screen to scroll forward. To select text, just move the mouse cursor to it and use any of the following mouse functions: Left button drag Select lines of text by holding down the left mouse button and dragging the mouse. Right button drag Select text bounded by a rectangular area by holding down the right mouse button and dragging the mouse. Left single click Paste the clipboard to the keyboard and cancel Scroll Lock. Any current text selection will be copied to the local clipboard first, and if the local clipboard is empty a copy of the Windows clipboard will be pasted. This action is the same as hitting the Insert key. There is one special case: If Scroll Lock was off and the 4DOS/NDOS popup command history window was showing, the current selected command will be executed as though Enter had been hit. Left double click Select the word under the mouse cursor, or if the mouse cursor is already within the text selection, add another word to the selection. This action is the same as hitting the Space bar. Right single click Add the current text selection to both the local and Windows clipboards. This is the same as hitting the Enter key. If there was no text selection, cancel Scroll Lock, release the mouse, and return to normal key entry (same as hitting the Escape key). Right double click Cancel the current selection or Scroll Lock. This is the same as hitting the Escape key. Middle single click Same as the Page Up key, except when the 4DOS/NDOS history window is showing, when it generates an Up arrow. Middle double click Same as the Page Down key, except when the 4DOS/NDOS history window is showing, when it is a Down arrow. The act of selecting text will turn on Scroll Lock if it is not already on. If you have a two button mouse, the functions for the "middle" button can be simulated by pressing both the left and right buttons simultaneously. 29 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. Changes made with SETCOLOR.exe are in effect only as long as your system is running. To change the colors for system startup, use the NEWAPLUS.exe program. SETCOLOR.exe is executed by a command of the form: SETCOLOR [ ...] where each selects a foreground or background color or other option. If no 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: 30 +--------------------------------------------------------+ | 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 (swaps) the current foreground and background colors SETCOLOR rev reverses foreground and background 31 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: = [ ...] where is the name of the user supplied color scheme, and 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 Save the current 16-color definitions in a file SAVE256 Save the 256 VGA DAC color definitions in a file LOADFILE Load a color definition file SAVECURRENT Save the 16 current colors as an executable program SAVEDEFAULT Save the 16 default colors as an executable program SAVEPROGRAM 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. 32 +------------------------------+ | 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. To provide additional user control over 16-color programs, such as DBASE III or DOS 5.0 EDIT.com, that set their own palettes or border colors but do not restore the palette on completion, or to simply force a color scheme on a program that defines its own, ANSIPLUS can lock the color palette, preventing a program from loading the PAL/DAC and border color registers by BIOS calls. This feature is controlled by two SETCOLOR options: LOCKPAL enable locked color palette, ignore BIOS calls defining colors UNLOCKPAL disable locked color palette, allow programs to define colors Palette locking should only be used when all other means of control fail. It is intended to be invoked as part of batch files that execute applications to be controlled, locking the palette before the program runs, and unlocking it after it completes. The feature should never be enabled all of the time because it will keep well behaved programs from making color changes too. 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 33 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 Ctrl+G beep tone. Changes made with SETAPLUS.exe are in effect only as long as your system is running. To change ANSIPLUS features for system startup, use the NEWAPLUS program. SETAPLUS.exe is executed by a command of the form: SETAPLUS [ ...] where each selects an ANSIPLUS feature or other option. As for the SETCOLOR.exe utility, if no 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 | | Tone | Ctrl+G beep tone generation options | | Keyboard | Caps Lock, Ctrl+C and key read-ahead options | | Assign | Key reassignment enable/disable option and key definition | | Color | Mode set color, blink, bright key echo and VGA mono options| | Display | Screen saver and graphics mode cursor options | | Scrollback| Scroll-back options | | Other | Scroll-Lock, smooth scrolling and copy/paste 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 35. 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 34 +-------------------------------------------------------------------+ | Table 4-5 | | SETAPLUS Feature Selection Keywords | +------------+------------------------------------------------------+ | SETCOLORS | Install ANSIPLUS colors on mode sets | | DOSSET256 | Load colors on DOS 256-color mode sets | | WINSET256 | Load colors on Windows 256-color mode sets | | NOBLINK | Enable 16-color text mode background (disable blink) | | BRIGHT | Highlight echoed keys (bright key echo) | | LOCKPAL | Prevent palette/DAC color changes by programs | | MONOCHROME | VGA monochrome monitor emulation | | RETRACE | Wait for retrace before setting palette registers | | | | | SAVER | Enable screen saver (blanker) | | EGASAVER | Use alternative method for blanking VGA screen | | VESAPOWER | Use VESA power management in screen saver | | READ60H | Read key controller scan codes in screen saver | | 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 | | CURSOR256 | Generate pseudo-cursor in 256-color graphics modes | | TTYTRAP | Trap ANSI escape sequences in BIOS Write TTY | | | | | STICKYSHIFT| Enable sticky shift keys | | CAPSUNLOCK | Unlock Caps Lock with shift/letter key combination | | CAPSRELOCK | Relock Caps with carriage return after shift/letter | | CTRLC | Generate Ctrl+Break when Ctrl+C is entered | | NDLAST | Read last key in buffer with non-destructive input | | REPEATZERO | Allow zero-key to repeat | | STACK | Enable key stacking | | | | | KEYASSIGN | Enable ANSI key reassignment | | BIOSASSIGN | Apply key reassignment at BIOS Int 16h level | | NODEFKEY | Prevent ANSI key reassignment redefinition | | | | | BEEP | Use ANSIPLUS Ctrl+G beep tone generator | | WINBEEP | Allow ANSIPLUS beep tone under Windows | | | | | SCROLLBACK | Enable scroll-back of lines scrolled off top | | DOSEMS | Use expanded memory for DOS scroll-back | | WINEMS | Use expanded memory for Windows scroll-back | | WINVRAM | Allow video RAM for Windows scroll-back | | XMSBACK | Preserve scroll-back data using XMS or HMA memory | | BIOSBACK | Capture lines scrolled by BIOS call | | CLSBACK | Capture erased pages never scrolled up | | REGIONBACK | Capture lines scrolled from subscreen regions | | PROTECTPAGE| Protect 2nd display page from scroll-back storage | | | | | LOCK | Allow Scroll Lock key to freeze screen | | ALTLOCK | Require Alt+Scroll-Lock when freezing screen | | SMOOTH | Enable smooth scrolling | | WINSMOOTH | Allow smooth scrolling under Windows | | SPEEDUP | Speed up smooth scroll when delaying computer | | SCROLL32BIT| Allow 32-bit block moves for text scrolling | | BIOSCROLL | Use BIOS calls for text mode screen scrolling | | MOUSELOCK | Require Scroll Lock for full screen mouse copy/paste | +------------+------------------------------------------------------+ 35 Other command line options include: MODE to set the video display mode, HEIGHT to set the text character height, PAGE to set the video page, KEYDEF to enter key reassignment definitions from the keyboard, LISTKEYS to list all current key reassignments, SAVEKEYS to save current key reassignments in a file, LOADKEYS to load key reassignment definitions from a file, KEYSTACK to add keys or delays to the keyboard buffer, RATE to set the keyboard "typematic" repeat rate, DELAY to set the typematic key delay, SAVESCROLLTEXT to save scrollback to a file (text only), SAVESCROLLANSI to save scrollback with ANSI color control, SAVECLIP to save the clipboard to a file, LOADCLIP to load the clipboard from a file, BLANKTIME to set the screen saver blanking time, SMOOTHRATE to set the smooth scrolling rate, TONE to set the Ctrl+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. Two keyword options are provided for managing the interrupt vectors used by ANSIPLUS: INTERRUPT Displays, to the extent possible, the chain of programs attached to each following selected interrupt LINK Relinks ANSIPLUS to the selected interrupt(s) You may specify interrupt selectors as either hexadecimal numbers or special keywords: KEYEVENT Interrupt 09h Key Event VIDEO Interrupt 10h Video SYSTEMSERVICE Interrupt 15h System Services KEYREQUEST Interrupt 16h Keyboard Request KEYBREAK Interrupt 1Bh Keyboard Break TIMERTICK Interrupt 1Ch User Timer Tick DOSCALL Interrupt 21h DOS Call DOSIDLE Interrupt 28h DOS Idle DOSTTY Interrupt 29h DOS Fast TTY Output MULTIPLEX Interrupt 2Fh Multiplex MSMOUSE Interrupt 33h Mouse PS2MOUSE Interrupt 74h PS/2 Mouse Event For example, SETAPLUS INTERRUPT 2F will list the programs attached to the DOS Int 2Fh Multiplex interrupt. 36 All the features controlled from the SETAPLUS command line are described in Chapter 3 under "Changing the ANSIPLUS Startup Configuration", starting on page 15, except for three: * To reassign keys, use the KEYDEF keyword. 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. * To add keys to the keyboard buffer, use the keyword KEYSTACK, followed by any number of quoted strings, key scan and character codes (scan code times 256 plus ASCII character code), or time delay directives (/Wnnn for timer ticks, or /Dnnn for milliseconds). The following example enters "Dir", waits one second, then enters " *.*" and a carriage return: SETAPLUS KEYSTACK "Dir" /W18 " *.*" 13 * 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 Ctrl+G beep. To define the beep sound from the SETAPLUS main menu, select Tone Definition and run through the feature options. 37 CREATING APPLICATION BATCH FILES Almost all DOS applications should run without change when ANSIPLUS is installed. However, in a few cases it may be desirable to create a batch file that prepares the system for an application, runs it, and then cleans up afterward. There are four common reasons for creating these application batch files: * To restore the normal DOS command shell video mode and colors after the program ends; * To install a color palette for the program to use when it runs; * To save key reassignments, change them, run a program, and restore the keys; * To enable or disable ANSIPLUS features that conflict with the program. Many DOS application programs do not completely restore the video state on completion. The common problems seen (with examples in parentheses) are: * The program sets the color palette, usually to the OEM default, but doesn't restore it on completion (DOS 5.0 EDIT.com, DBASE III). * The program sets the border color, but doesn't restore it, or sets it to black on completion (DBASE III). * The program turns blink on, but doesn't restore it on completion (DOS 5.0 EDIT.com, DBASE III). * The program selects a video mode, but doesn't restore the original one on completion (DOS 5.0 EDIT.com, DBASE III). * The program selects a video mode and restores it on completion, but doesn't restore the text height if it is not standard for the video mode (Quattro Pro 3.0 and others). There are four simple options for restoring the ANSIPLUS video mode and colors after running an application that sets its own mode, palette or border color: * The first option can be used to restore only the border color after an application has run. Suppose the border color is normally palette code 17, then the following batch file will set the border after the application (in this example, DOS EDIT.com) runs: @ECHO OFF C:\DOS\EDIT.com %1 %2 %3 %4 %5 %6 %7 %8 %9 SETCOLOR BORDER 17 * The second option will restore the entire default ANSIPLUS palette and border color after the application runs: @ECHO OFF C:\DOS\EDIT.com %1 %2 %3 %4 %5 %6 %7 %8 %9 SETCOLOR RESET 38 * The third option requires creating a small .com file that will load an entire color scheme. This can be done at any time by hitting the letter "S" from the SETCOLOR.exe palette definition screen, or it can be done from the DOS command level with a command like: SETCOLOR SAVEPROGRAM MYCOLORS This will create a program called MYCOLORS.com, which loads the 16-color palette and border colors that were in effect when the program was created. The batch file for the application can then use this program to restore the color scheme on completion: @ECHO OFF C:\DOS\EDIT.com %1 %2 %3 %4 %5 %6 %7 %8 %9 MYCOLORS * The fourth option saves and restores the video mode, character height and foreground/background color selection, and loads the ANSIPLUS default palette after the application completes. The batch file uses the PUSHVID.com and POPVID.com programs provided with ANSIPLUS: @ECHO OFF PUSHVID C:\DOS\EDIT.com %1 %2 %3 %4 %5 %6 %7 %8 %9 POPVID This is the best technique to use when running DOS in a text mode other than 25 lines by 80 columns, because it will restore both the video display mode and text height. The options for controlling colors used by applications depend on whether custom colors are desired for the application and whether the application loads its own palette: * If the application ordinarily uses ANSIPLUS's colors when it runs, then it will use any ANSIPLUS color palette in effect when it begins execution, so a .com color scheme file saved from the SETCOLOR.exe palette definition screen, or by a SETCOLOR SAVEPROGRAM APPCOLOR command, can be used to load a custom color scheme before running the application: @ECHO OFF APPCOLOR %1 %2 %3 %4 %5 %6 %7 %8 %9 MYCOLORS Because most DOS application programs select a video mode when they start up, be sure that the color scheme saved in APPCOLOR.com is saved as a default color scheme. 39 * To use the ANSIPLUS palette for an application that installs its own palette, the palette must be locked before the program starts and unlocked after it completes: @ECHO OFF LOCKPAL %1 %2 %3 %4 %5 %6 %7 %8 %9 UNLOKPAL Warning: Palette locking should only be used when all other means of control fail. The feature should never be left enabled all of the time because it will keep well behaved programs from making any color changes. * To use custom colors for an application that wants to install its own palette, the custom colors are loaded before the palette is locked: @ECHO OFF APPCOLOR LOCKPAL %1 %2 %3 %4 %5 %6 %7 %8 %9 UNLOKPAL MYCOLORS If you run your system using a certain set of ANSI key reassignments most of the time, but also run an application that sets up its own key reassignments, the PUSHKEYS.com and POPKEYS.com programs supplied with ANSIPLUS can be used in a batch file to save the keys before the application is started and to restore them after it completes: @ECHO OFF PUSHKEYS %1 %2 %3 %4 %5 %6 %7 %8 %9 POPKEYS If you want to set up a special set of key reassignments before running an application, just define the reassignments using the SETAPLUS utility program, and then save them to a file (in this example, named APPKEYS.com) with a SETAPLUS SAVEKEYS APPKEYS.com command. You then run APPKEYS.com in your batch file after saving the keys, but before the application: @ECHO OFF PUSHKEYS APPKEYS %1 %2 %3 %4 %5 %6 %7 %8 %9 POPKEYS In the event of a conflict between an ANSIPLUS feature and an application, the feature can be disabled before running the application and enabled again after it completes. For example, the following batch file turns off the screen saver while running an application: @ECHO OFF SETAPLUS DISABLE SAVER %1 %2 %3 %4 %5 %6 %7 %8 %9 SETAPLUS ENABLE SAVER 40 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 where 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. 41 V. ANSIPLUS ESCAPE SEQUENCES This chapter lists and briefly describes each of the "ANSI" Escape sequences recognized by ANSIPLUS. They are described in detail only in the printed ANSIPLUS User's Guide. 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 Esc [!#;...#e Select graphics mode text treatment options Esc [!#v Select video page Esc [#U Select next page Esc [#V Select preceding 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 [#E Move cursor to next line Esc [#F Move cursor to preceding line Esc [#G Move cursor to absolute column in same line Esc [#a Move cursor to absolute line in same column Esc [#;#;#g Reset tabs Esc [#;...#W Tab control Esc [#I Horizontal tab Esc [#Y Vertical tab Esc [#Z Backward tab Esc [#;#s Save cursor position or other driver context Esc [#;#u Restore cursor position or other driver context 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 42 Control Sequence Description ---------------- ----------- ERASE, INSERT AND DELETE Esc [#;#J Clear the screen Esc [#;#;#K Clear the current line Esc [#;#X Erase characters on the current line Esc [#;#L Insert lines on the screen Esc [!#;#L Insert lines from scroll-back Esc [#;#M Delete lines from the screen ESc [!#;#M Delete lines and add to scroll-back Esc [#;#@ Insert characters on a line or a column range Esc [#;#P Delete characters from a line or a column range Esc [#b Repeat last output character Esc [#;#;#;#;#S Scroll up Esc [!#;#;#;#;#S Scroll up and add to scroll-back Esc [#;#;#;#;#T Scroll down Esc [!#;#;#;#;#T Scroll down from scroll-back Esc [#;#;#;#;# @ Scroll left (Note: a Space must precede "@") Esc [#;#;#;#;# A Scroll right (Note: a Space must precede "A") Esc [#;#;#;#r Set scrolling region 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 Ctrl+G beep tone Esc [#;...#p Define key reassignment (accepts quoted strings) Esc [!#;...#k Add keys to keyboard buffer (accepts quoted strings) Esc [!#w Wait for specified time to elapse 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 "ANSIPLUS Extensions and the ANSI Standard" on page 51 for differences between ANSIPLUS and the ANSI.sys driver. 43 VI. TECHNICAL NOTES ANSIPLUS AND WINDOWS Users of Windows 95 and 3.x should consider using ANSIPLUS as well. The ANSIPLUS driver works well with DOS programs under Windows, 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. This section discusses how to work around the few limitations imposed on ANSIPLUS DOS sessions by Windows or by Windows in combination with other software. Loading Options All ANSIPLUS memory loading options are compatible with Windows, with the following exceptions: * Under Windows 95, ANSIPLUS's code cannot be loaded into EMS memory unless an EMS memory manager is loaded explicitly by a DEVICE= command in CONFIG.sys before ANSIPLUS. If EMM386 is loaded automatically as Windows 95 initializes, it will be loaded AFTER ANSIPLUS, so EMS memory will not exist when ANSIPLUS is installed by MS-DOS 7. * ANSIPLUS's code cannot be loaded to the HMA under MS-DOS 7 (Windows 95) because there apparently is not enough unused HMA memory available. * When the ANSIPLUS code has been loaded into expanded memory, Version 6 of 386MAX (and possibly other versions) will refuse to let Windows 3.x start in 386 Enhanced mode. The 386MAX memory manager complains that expanded memory cache software is running. This limitation does not exist for the EMM386 or QEMM386 memory managers. To get Windows to run with ANSIPLUS and 386MAX, load the ANSIPLUS driver into XMS upper memory, HMA, or low memory instead. * If Windows 3.0 (not 3.1, 95 or NT!) will be run in 386 Enhanced mode, it is strongly recommended that the entire ANSIPLUS driver (or any other ANSI driver) not be loaded into high memory by DEVICEHIGH or equivalent, 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! Beep Tone When Windows is running in 386 Enhanced mode, and a DOS program running in the background outputs a Ctrl+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. 44 Copy and Paste When key input is pasted from the Windows clipboard, it is made available to programs by ANSIPLUS via the Int 16h key input interrupt. But Microsoft, in their wisdom, has disabled Int 2Fh/AH=17h access to the Windows clipboard by a virtual DOS machine while it is executing an Int 16h key input interrupt. To get around this limitation, ANSIPLUS copies data to and from the Windows clipboard in the background during hooked Int 28h DOS Idle, Int 1Ch User Timer Tick and Int 21h DOS call interrupts. However: * Under Windows 95, it appears that the Int 28h DOS Idle call is never executed by each virtual DOS machine. Under Windows 3.1, it is. * In Windows 3.x, some networks (eg., NetWare) add a "TimerCriticalSection=" line to SYSTEM.ini. Windows 95 does not support this line in SYSTEM.ini, but on a Novell network behaves as though it did. According to Novell, the reason for the TimerCriticalSection line is to avoid a deadlock in its LAN IRQ Virtualization code. Unfortunately, this keeps the ANSIPLUS Int 1Ch hook from executing properly in each virtual DOS machine, and because of this, text might not be pasted to those MS-DOS programs that use Int 16h for key input instead of standard DOS key input if they don't also make Int 21h DOS calls while waiting for key input. Removing the TimerCriticalSection line from SYSTEM.ini may fix the problem, but you should do this only if you have trouble pasting data, and you should test your system carefully to be sure this doesn't introduce problems with network access. Full Screen vs. Windowed DOS Sessions The VWFD.386 Windows Virtual Device Driver for Windows 3.x or 95, which is supplied with ANSIPLUS, is required to test whether a DOS virtual machine is full screen or in a window. If the VWFD.386 driver is not installed, ANSIPLUS will have no way of knowing whether it is running full screen under Windows, so it must assume that a DOS session is in a window and disable three features: * The ANSIPLUS screen saver: The screen should be blanked by ANSIPLUS only when a DOS session is full screen; the Windows screen saver should have control when the DOS session is in a window. * Smooth scrolling: This should operate correctly for full screen DOS programs under Windows. However, when a DOS session is run in a window, the direct access to video controller I/O ports required for smooth scrolling may interfere with some Windows 3.x video display drivers. For example, the 256-color drivers for the Tseng ET4000 may leave undrawn black areas on the screen when scrolling occurs in a window while smooth scrolling is active. Because of this, smooth scrolling must be prevented when a DOS session is in a window, and allowed only when it is full screen. * Mouse copy/paste when Scroll Lock is off: When a DOS session is running in a window, the user can move the mouse all over the screen, sometimes crossing over the DOS session window. Because of this, ANSIPLUS will not "wake up" the mouse when running in a window unless the Scroll Lock key has been pressed. The ANISIPLUS INSTALL program will automatically copy the VWFD.386 file to the WINDOWS\SYSTEM directory, and will add the following line to the [386Enh] section of the Windows SYSTEM.ini file: DEVICE=VWFD.386 45 Scroll-Back The recommended storage location for scroll-back data under Windows is expanded memory (EMS). Use of EMS for scroll-back instead of video RAM (as was done by ANSIPLUS drivers before Release 3.10) eliminates compatibility problems with Windows video drivers apparently caused by memory accesses to video RAM not on the visible part of the virtual screen. The standard Windows 3.x DOSPRMPT.pif and _DEFAULT.pif files both allow programs to access EMS memory. A sample PIF file with suggested PIF settings (for the MS-DOS prompt) is included with the ANSIPLUS package in the file APLUS.pif. These settings are recommended, but not necessary, for all DOS applications that depend on scroll-back under Windows. Under Windows, when a 386 Enhanced Mode DOS session starts, ANSIPLUS will try to allocate 64K of private expanded memory (EMS) for scroll-back (48K if ANSIPLUS code was loaded into EMS). If the EMS is not available (for example, if the Windows PIF file for the application does not provide expanded memory), then the driver will attempt to use video RAM for scroll-back instead, if that option has been specifically enabled. ANSIPLUS provides a configurable feature that can prevent Windows EMS from being allocated for scroll-back and force any Windows DOS session scroll-back to reside in video RAM. This is not advised, however, because scroll-back in video RAM under Windows is not reliable when used with many Windows video drivers. Using video RAM for scroll-back under Windows 3.x has problems, particularly for DOS applications run in a window. One difficulty is that when a DOS application is run in 386 Enhanced Mode, Windows will not maintain a full 32K of text mode RAM unless the Windows PIF file specifies "High Graphics" and "Retain Video Memory". If these PIF settings are not used, then the first time that ANSIPLUS needs to access the scroll-back storage area, Windows may present a message claiming that there is not enough memory for the application to correctly display information. If this happens, just click on OK, then hit Alt+Enter to switch to a full screen display and proceed. Scroll-back data will also likely be lost when the focus is switched from task to task, as with the Alt+Tab key, or when changing display modes. Even with these PIF settings, some Windows 3.x video drivers (eg., 256-color ET-4000) will not work correctly when video RAM outside the visible screen is accessed, resulting in loss of scroll-back text or incomplete updating of the screen. You therefore should exercise caution before relying on video RAM for scroll-back under Windows. Starting with ANSIPLUS Release 3.10, scroll-back lines are captured under Windows as they are completed, rather than as they scroll off the top of the screen. This change was necessary because some Windows video drivers (eg., Microsoft VGA) trap BIOS scrolling requests completely and do not pass them through to the DOS virtual 8086 when running a DOS session in a window. This makes it impossible for ANSIPLUS to know when the screen has scrolled if a BIOS call was used to do it. Some important DOS programs now mix DOS output and BIOS calls for scrolling (eg., 4DOS 5.0 and NDOS 8.0 when displaying multi-colored directories). 46 Color Palettes Full screen DOS programs in Windows will use the same colors as they do when run under DOS. When the same program is run in a window, its 16-color palette will be determined entirely by Windows and the Windows video driver. ANSIPLUS will have no control over the palette when running in a window. Under Windows, when a DOS session is run in a window using Microsoft's VGA video driver (and possibly others), ANSIPLUS's pink color may appear as white. This can be corrected by converting pink to light magenta with the WINVGA16.com program provided with ANSIPLUS. Including WINVGA16.com in AUTOEXEC.bat will change pink to light magenta for all DOS applications in and out of Windows. Running it within a Windows DOS session will change the color for only that DOS session. However, WINVGA16.com will not work if run in WINSTART.bat because it is not a TSR. Some 256-color drivers for Windows apparently assume that the OEM 256-color palette has been loaded when the 256-color mode was selected, and never define the colors that Windows will use. Because of this, ANSIPLUS normally does not load its default colors when a 256-color mode is selected under Windows. This can be overridden by a configurable feature. International Usage When the DISPLAY.sys driver is used with Windows 3.x, the colors and other variables of either ANSIPLUS or the DOS ANSI.sys driver are not localized to each virtual 8086. This appears to be because DISPLAY.sys is a CON device driver that calls the previous CON driver (i.e., ANSIPLUS) to control the console, so DOS actually has two CON drivers active at the same time. Windows only localizes the first CON driver it finds on the DOS device chain, and this will be the most recent CON device installed, which is DISPLAY.sys, not ANSIPLUS. Two system setup changes are required to circumvent the problem: (1) Enter the following command to change the name of the ANSIPLUS driver in memory from "CON" to "CONAPLUS": SETAPLUS LOCALCON This command is automatically inserted into AUTOEXEC.bat by the ANSIPLUS INSTALL program when DISPLAY.sys is detected. (2) Add the following command to the [386Enh] section of the Windows SYSTEM.ini file (put it right after the "LOCAL=CON" line): LOCAL=CONAPLUS This causes Windows to localize the ANSIPLUS driver to each virtual 8086. The ANSIPLUS INSTALL program automatically adds this line to SYSTEM.ini. If the DISPLAY.sys driver is in use and ANSIPLUS code has been loaded into expanded memory, the SETAPLUS LOCALCON command must be executed before Windows is started, and the LOCAL=CONAPLUS line MUST be added to SYSTEM.ini, and CONAPLUS must be CAPITALIZED! If it is not, Windows will probably crash the first time a DOS program or session is started. These system setup changes are totally unnecessary if the DISPLAY.sys driver is not being used. 47 ANSIPLUS AND THE 4DOS OR NDOS COMMAND SHELLS The ANSIPLUS driver is compatible with the 4DOS and NDOS command shells. Three ANSIPLUS features are specifically adapted to 4DOS/NDOS: * ANSIPLUS supports key stacking (for 4DOS 4.0+ and NDOS Version 7.0+), so the KSTACK.com TSR does not need to be loaded. When ANSIPLUS key stacking is enabled, ANSIPLUS emulates the 4DOS/NDOS Int 2Fh function D44Fh key stacking interface, so the 4DOS/NDOS KEYSTACK command will work, and loading the KSTACK.com driver will report that it is already installed. ANSIPLUS key stacking capacity is limited to the size of ANSIPLUS's key buffer, which is configurable by INSTALL/NEWAPLUS up to 512 keys. ANSIPLUS key stacking can be disabled if KSTACK.com or KEYSTACK.sys is preferred. * The SETCOLOR.exe utility program can be used as a replacement for the 4DOS or NDOS internal COLOR command, since SETCOLOR supports the syntax and all options of COLOR, plus many additional options. To do this, two commands should be added to AUTOEXEC.bat: SETDOS /I-COLOR ALIAS COLOR SETCOLOR Effective with 4DOS 5.5, color numbers are supported by the 4DOS internal COLOR command. The ANSIPLUS SETCOLOR.exe utility program has always supported color selection by number, but using a different numerical order. If compatibility with 4DOS's color ordering is desired, the "/4DOS" command tail option should be added to the ALIAS: SETDOS /I-COLOR ALIAS COLOR SETCOLOR /4DOS * At the 4DOS command prompt, when ANSIPLUS controls the mouse, clicking the middle mouse button (or both left and right buttons simultaneously) can be used to bring up the 4DOS popup history window. When the history window is showing, holding down the middle button will scroll up and down in the history. Clicking the left button will select the highlighted item, and clicking the right button will cancel the history selection. One compatibility issue can arise for users who want to squeeze 4DOS output into a subscreen window: When a subscreen region has been defined by ANSIPLUS, 4DOS will not normally write colored directory names or other directly addressed screen output (eg., SCRPUT) to the correct locations in the subscreen region. This can be corrected by adding the following line to 4DOS.ini: OutputBIOS=Yes You should also consider removing the following lines from 4DOS.ini/NDOS.ini: BrightBG= Turning bright background on or off in the command shell will override the ANSIPLUS background/blink setting StdColors= These colors will override the startup colors defined by the NEWAPLUS utility program InputColors= Use this only if you want to highlight input keys with a color other than the bright white provided by ANSIPLUS 48 ANSIPLUS AND MULTITASKERS OR TASK SWITCHERS OS/2 The ANSIPLUS INSTALL program can recognize and alter the OS/2 CONFIG.sys file just as it can for MS-DOS. Once ANSIPLUS is installed, it will be available to all OS/2 full screen and windowed DOS sessions. ANSIPLUS features will not be available to OS/2 sessions because ANSIPLUS is currently a DOS, not an OS/2 device driver. Only a few other issues affect ANSIPLUS under OS/2: * Screen scroll-back data will exist only as long as the virtual DOS machine that created it exists, so scroll-back will not be available from one command to another under the OS/2 command shell, but it will be available when you are using a DOS command shell in a virtual DOS machine. * The $i PROMPT, which is part of the default prompt inserted by OS/2 install, interferes with ANSIPLUS scroll-back because at every DOS command shell prompt the top line on the screen is replaced by an OS/2 help message. When the screen scrolls, this message is then added to scroll-back instead of the original content of the top line. It is best to remove the $i from your DOS prompt, but if you want to keep on using it, you should replace the $i with the prompt sequence $e[s$e[H$e[K$i$e[u, which will save the top line to scroll-back before the OS/2 help message is put there. * You must disable VIDEO_RETRACE_EMULATION if you want to use smooth scrolling in full screen DOS sessions. Otherwise, OS/2 will ignore ANSIPLUS's smooth scrolling control. Rough scrolling always applies in DOS windows. * Because virtual DOS machines are created and initialized so often by OS/2, the ANSIPLUS signon message is suppressed when ANSIPLUS is loaded as a device driver by CONFIG.sys. When ANSIPLUS.exe is loaded as a TSR, the signon message will always be displayed. The unregistered Shareware driver will display the ANSIPLUS signon (with the 9 second delay) about one percent of the time when it initializes in a new virtual DOS machine. DESQview Because of DESQview's handling of device drivers loaded before it starts, and because it takes over an interrupt vector used by ANSI drivers, DESQview presents a challenge for an attached console driver like ANSIPLUS: * If a device driver, such as ANSIPLUS, is loaded before DESQview is started, a single copy of the driver will be shared by all DESQview windows (virtual 8086's), because DESQview does not create local copies for each window. This means, for example, that changing colors by ANSI escape sequence in one window would affect the colors used in other windows. * As each DESQview window is created, the Int 29h fast console output interrupt, which ANSIPLUS and other ANSI drivers depend on to receive much of their character output, is taken over by DESQview. This means that DOS output, including ANSI escape sequences, will never be processed by the driver, because DESQview will get it first. Because of these problems, any console driver that will be used in a DESQview window must be loaded as a TSR after the window has started. The best method is to create a batch file that loads ANSIPLUS and does anything else needed to set up the window, and then executes the command associated with the window. 49 And there are a few more complications: * It is desirable to use ANSIPLUS both inside and outside of DESQview. This means that if an ANSIPLUS driver is already loaded when DESQview is started, it should detect this event so that the driver can disable itself. When DESQview terminates, the disabled driver must then reactivate itself. * To save memory, any TSR copies of ANSIPLUS loaded in a window should be able to execute using shared code from the ANSIPLUS driver loaded before DESQview, so that the TSR copy in each window will require only about 6K. * Expanded memory, which is used by ANSIPLUS to hold its scroll-back data and sometimes its code, is managed globally under DESQview, so the ANSIPLUS driver must allocate separate EMM handles for scroll-back and assign them different names in each DESQview window. The registered ANSIPLUS.exe device driver satisfies all these requirements. The Shareware ANSIPLUS.sys driver, however, cannot be loaded as a TSR except by another program, such as Quarterdeck's DEVICE.com. And because loading the CON device driver ANSIPLUS.sys will change the system console, DEVICE.com does not appear to completely install the driver, at least as far as the MS-DOS command shell, COMMAND.com, is concerned. This must be corrected by entering a CTTY CON command in each window after ANSIPLUS.sys has been loaded. The ANSIPLUS driver is DESQview aware: After it is loaded in a DESQview window, it uses alternative video buffers for video output if the screen is not "virtualized", calls the BIOS for cursor positioning instead of writing directly to the video controller, releases time slices when waiting for key input, disables the ANSIPLUS screen saver, and prevents video RAM from being used to store scroll-back (EMS scroll-back is still allowed). Task Switchers When a task switcher, such as MS-DOS DOSSHELL, is running, the user should have independent ANSIPLUS consoles for each task. To provide this functionality, ANSIPLUS supports the Microsoft Int 2Fh functions 4B01h-4B05h task switcher interface, which is used by both DOSSHELL and Windows 3.x Standard Mode. Via the interface, ANSIPLUS reports its instance data to the task switcher and monitors switcher activity to control allocation and destruction of EMS handles for session scroll-back, if the task switcher allows this. ANSIPLUS should also work with other task switchers that support this interface. 50 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 or the MS-DOS ANSI.sys driver, 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 [!#;#L Insert lines from scroll-back Esc [!#;#M Delete lines and add to scroll-back Esc [!#;#;#;#;#S Scroll up and add to scroll-back Esc [!#;#;#;#;#T Scroll down from scroll-back Esc [!#;...#d Enable or disable ANSIPLUS driver features Esc [!#;...#g Define Ctrl+G beep tone Esc [!#;...#k Add keys to keyboard buffer Esc [!#w Wait for specified time to elapse The following ANSI control sequences accept both standard ANSI parameters and extra ANSIPLUS parameters, but are not included in MS-DOS ANSI.sys: Esc [#;#g Reset tabs Esc [#;...#W Tab control Esc [#;#X Erase characters on the current 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 [#;#;#;#;#S Scroll up Esc [#;#;#;#;#T Scroll down Esc [#;#;#;#;# @ Scroll left Esc [#;#;#;#;# A Scroll right Esc [#;#;#;#r Set scrolling region The following are standard ANSI terminal control sequences that are not included in MS-DOS ANSI.sys: Esc [#U Select next page Esc [#V Select preceding page Esc [#E Move cursor to next line Esc [#F Move cursor to preceding line Esc [#G Move cursor to absolute column in same line Esc [#a Move cursor to absolute line in same column Esc [#I Horizontal tab Esc [#Y Vertical tab Esc [#Z Backward tab Esc [#b Repeat last output character The following control sequences, which are also included in ANSI.sys, accept both standard ANSI parameters and extra ANSIPLUS parameters: Esc [#;#h Set video mode Esc [#;#s Save cursor position or other driver context Esc [#;#u Restore cursor position or other driver context Esc [#;#J Clear the screen 51 Esc [#;#;#K Clear the current line Esc [#;...#m Select current color attributes for output characters Esc [#;#n Query ANSIPLUS status: cursor position, colors, etc. Esc [#;...#p Define key reassignment The following are ANSI sequences that are in both MS-DOS ANSI.sys and ANSIPLUS: Esc [#A Move cursor up Esc [#B Move cursor down Esc [#C Move cursor right Esc [#D Move cursor left 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. Note, however, that a blank space immediately before the ANSI command letter may be significant. For example, Esc [A moves the cursor up, while Esc [ A scrolls the screen left; * 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 65,535) are accepted for certain commands. Plus and minus signs are also accepted. Unrecognized escape sequences are passed through by the driver unaltered. With a few exceptions, 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. The exceptions are Esc E, Esc H and Esc J, which are all ANSI standard. 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 in four cases: * Graphics modes with 256 or more colors; * Graphics modes that require more than 64K bytes of video RAM (i.e., 16 color graphics modes exceeding 800x600 resolution). * Unrecognized (usually CGA or Hercules) display modes. * All graphics modes under the reduced capability ANSIPLSR.sys driver. When BIOS calls are used, output is much slower, and "transparent" mode output, graphics mode text treatments, insert/delete characters and scroll left/right are also not supported. Future versions of ANSIPLUS may extend direct video RAM access to some of these modes. 52 INSTALLATION CHECK AND INTERRUPT 2FH API ANSIPLUS responds to the Interrupt 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. Besides responding to the MS-DOS ANSI.sys Int 2Fh functions, the ANSIPLUS driver also supports several Int 2Fh calls of its own, which provide infrequently needed or special functions that programmers and the ANSIPLUS utility programs may need, but that general users will not need. This application program interface (or "API") currently includes functions for detecting the presence and version number of the ANSIPLUS driver, reporting on the status of the ANSIPLUS driver, disabling or enabling the driver or certain driver features, accessing screen lines saved for scroll-back, accessing the clipboard, controlling the screen saver blanking time, key repeat rate and smooth scrolling rate, loading the VGA/EGA character generator without affecting colors, and emulating 4DOS/NDOS key stacking. Full descriptions for all of the ANSIPLUS Interrupt 2Fh functions are included only in the printed ANSIPLUS User's Guide. The following description documents one function, the ANSIPLUS Installation Check: AX=1A00h: ANSIPLUS Installation Check Version: 2.00 or later Purpose: Provide emulation of the MS-DOS ANSI.sys installation check, with an extension to identify ANSIPLUS. The Int 29h segment returned by this function is used by ANSIPLUS utility programs to access variables within the running ANSIPLUS driver. Arguments: AX = 1A00h BX = 'AN' (414Eh) CX = 'SI' (5349h) DX = '++' (2B2Bh) Results: AL = 0 CH = major ANSIPLUS version number (3.10 or later) CL = minor ANSIPLUS version number (3.10 or later) DL = 00h for full capability driver (4.00 or later) 01h for reduced capability driver (4.00 or later) 2Bh full capability driver (before 4.00) other values reserved for future use ES:BX = ANSIPLUS Int 29h entry point If the BX, CX and DX arguments do not all match the magic argument values above, then BX, CX, DL and ES will not be altered on return. CX was not returned for driver versions before 3.10, so register CX will return 5349h for the earlier versions. The minor version number returned in CL is coded as two hexadecimal nibbles. Thus, for Release 3.10, CL will return 10h. 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, "4.04". 53 HOOKED INTERRUPTS To implement all of its features, ANSIPLUS attaches itself to up to twelve system interrupts. Two are replaced (1Bh and 29h), and the remaining ten 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 | +----------------------+------------------------------------------------------+ |09h Key Event | Screen saver; scroll lock; scroll-back; key buffer | | | extension; repeated key suppression; 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; set scrollable region | | | | |15h System Services | Key processing | | | | |16h BIOS Get Key | Key buffer management; highlighted key echo; scroll | | | lock and scroll-back; key reassignment; key stacking;| | | key repeat rate; copy and paste | | | | |1Bh Keyboard Break | Promote Ctrl+Break to front of key buffer | | | | |1Ch User Timer Tick | Screen saver; smooth scroll; color blinking; beep | | | tone generation; copy and paste | | | | |21h DOS Call | Copy and paste | | | | |28h DOS Idle | Copy and paste | | | | |29h DOS Write Char | Faster DOS screen output | | | | |2Fh Multiplex | Installation checks; ANSIPLUS special functions API; | | | Windows initialization and exit processing; 4DOS/NDOS| | | key stacking; DESQview detection; task switching; | | | command prompt detection; OS/2 CLS command | | | | |33h MS Mouse | Copy and paste; set scrollable region | | | | |74h PS/2 Mouse Event | Screen saver; set scrollable region | +----------------------+------------------------------------------------------+ 54 The MS-DOS KEYB program for international keyboard support hooks the Int 09h Key Event interrupt without passing calls through to whatever was installed before (i.e., to ANSIPLUS). However, the Novell DOS version of KEYB does pass calls through to the prior Int 09h handler. Therefore, under MS-DOS (but not Novell DOS) if the KEYB program is being used to set up the keyboard, the following command MUST be executed after loading KEYB, otherwise most ANSIPLUS keyboard related features will not work: SETAPLUS LINK KEYEVENT This command will re-install ANSIPLUS on the key event interrupt. The INSTALL program will automatically add this command to AUTOEXEC.bat if it finds a reference in it to KEYB and you are not using Novell DOS. If the DISPLAY.sys device driver for code page switching is being used, the ANSIPLUS.sys device driver must be installed before DISPLAY.sys in CONFIG.sys. The INSTALL program will also automatically handle this. If you suspect that a system interrupt is no longer accessible to ANSIPLUS because of a TSR or device driver that has been loaded after ANSIPLUS, you can test this with the command: SETAPLUS INTERRUPT which displays, to the extent possible, the chain of programs attached to any selected interrupt. The may be either a hexadecimal interrupt number or one of the following keywords: KEYEVENT Interrupt 09h Key Event VIDEO Interrupt 10h Video SYSTEMSERVICE Interrupt 15h System Services KEYREQUEST Interrupt 16h Keyboard Request KEYBREAK Interrupt 1Bh Keyboard Break TIMERTICK Interrupt 1Ch User Timer Tick DOSCALL Interrupt 21h DOS Call DOSIDLE Interrupt 28h DOS Idle DOSTTY Interrupt 29h DOS Fast TTY Output MULTIPLEX Interrupt 2Fh Multiplex MSMOUSE Interrupt 33h Mouse PS2MOUSE Interrupt 74h PS/2 Mouse Event If ANSIPLUS is missing from the listing, it can be relinked with the command: SETAPLUS LINK 55